Workflow-Befehle für GitHub-Aktionen

Informationen zu Workflow-Befehlen

Aktionen können mit dem Runner-Rechner kommunizieren, um Umgebungsvariablen zu setzen, Werte zur Verwendung in anderen Aktionen auszugeben, Debug-Meldungen zu den Ausgabeprotokollen zuzufügen und für andere Zwecke.

Workflow-Befehle verwenden den Befehl echo in einem bestimmten Format.

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Workflow-Befehle verwenden, um auf Funktionen des Toolkits zuzugreifen

Das actions/toolkit enthält eine Reihe von Funktionen, die als Workflow-Befehle ausgeführt werden können. Verwende die Syntax ::, um die Workflow-Befehle in Deiner YAML-Datei auszuführen. Diese Befehle werden dann über stdout an den Runner gesandt. For example, instead of using code to set an output, as below:

core.setOutput('SELECTED_COLOR', 'green');

You can use the set-output command in your workflow to set the same value:

      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: random-color-generator
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

Die folgende Tabelle zeigt, welche Toolkit-Funktionen innerhalb eines Workflows verfügbar sind:

Toolkit-Funktion	Äquivalenter Workflow-Befehl
core.addPath
add-path
core.debug	debug
core.error	error
core.endGroup	endgroup
core.exportVariable
set-env
core.getInput	Zugänglich durch Umgebungsvariable INPUT_{NAME}
core.getState	Zugänglich durch Umgebungsvariable STATE_{NAME}
core.isDebug	Zugänglich durch Umgebungsvariable RUNNER_DEBUG
core.saveState	save-state
core.setFailed	Wird als Abkürzung für ::error und exit 1 verwendet
core.setOutput	set-output
core.setSecret	add-mask
core.startGroup	Gruppe
core.warning	warnung

Setting an environment variable

::set-env name={name}::{value}

Creates or updates an environment variable for any steps running next in a job. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. Bei Umgebungsvariablen wird die Groß- und Kleinschreibung berücksichtigt. Sie können auch Satzzeichen enthalten.

Beispiel

echo "::set-env name=action_state::yellow"

Setting an output parameter

::set-output name={name}::{value}

Legt den Ausgabeparameter einer Aktion fest.

Optional kannst Du auch Ausgabeparameter in der Metadaten-Datei einer Aktion deklarieren. Weitere Informationen findest Du unter „Metadaten-Syntax für GitHub Actions“.

Beispiel

echo "::set-output name=action_fruit::strawberry"

Adding a system path

::add-path::{path}

Fügt für alle nachfolgenden Aktionen im aktuellen Auftrag vor der Systemvariablen PATH ein Verzeichnis hinzu. Die gerade ausgeführte Aktion kann nicht auf die neue Pfadvariable zugreifen.

Beispiel

echo "::add-path::/path/to/dir"

Setting a debug message

::debug::{message}

Gibt eine Debugging-Meldung im Protokoll aus. Du musst ein Geheimnis mit dem Namen ACTIONS_STEP_DEBUG und dem Wert true erstellen, um die durch diesen Befehl gesetzten Debugging-Meldungen im Protokoll zu sehen. For more information, see "Enabling debug logging."

Beispiel

echo "::debug::Set the Octocat variable"

Setting a warning message

::warning file={name},line={line},endLine={endLine},title={title}::{message}

Erstellt eine Warnmeldung und fügt die Mitteilung in das Protokoll ein. This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file.

| Parameter | Value | | :- | :- | | file | Filename | | col | Column number, starting at 1 | | line | Line number, starting at 1 |

Beispiel

echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Setting an error message

::error file={name},line={line},endLine={endLine},title={title}::{message}

Erstellt eine Fehlermeldung und fügt die Mitteilung in das Protokoll ein. This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file.

| Parameter | Value | | :- | :- | | file | Filename | | col | Column number, starting at 1 | | line | Line number, starting at 1 |

Beispiel

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Grouping log lines

::group::{title}
::endgroup::

Creates an expandable group in the log. To create a group, use the group command and specify a title. Anything you print to the log between the group and endgroup commands is nested inside an expandable entry in the log.

Beispiel

echo "::group::My title"
echo "Inside group"
echo "::endgroup::"

Masking a value in log

::add-mask::{value}

Das Maskieren eines Werts verhindert, dass ein String oder eine Variable im Protokoll ausgegeben werden. Jedes maskierte Wort, getrennt durch Leerzeichen, wird durch das Zeichen * ersetzt. Du kannst eine Umgebungsvariable oder einen String für den Wert (value) der Maske verwenden.

Beispiel für das Maskieren eines Strings

Wenn Du "Mona The Octocat" im Protokoll ausgibst, siehst Du "***".

echo "::add-mask::Mona The Octocat"

Beispiel für das Maskieren einer Umgebungsvariablen

Wenn Du die Variable MY_NAME oder den Wert "Mona The Octocat" ins Protokoll ausgibst, siehst Du "***" statt "Mona The Octocat".

MY_NAME="Mona The Octocat"
echo "::add-mask::$MY_NAME"

Stopping and starting workflow commands

::stop-commands::{endtoken}

Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command. Du kannst beispielsweise die Protokollierung anhalten, um ein vollständiges Skript mit Kommentaren auszugeben.

To stop the processing of workflow commands, pass a unique token to stop-commands. To resume processing workflow commands, pass the same token that you used to stop workflow commands.

::{endtoken}::

Example stopping and starting workflow commands

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: disable workflow commands
        run: |
          echo '::warning:: this is a warning'
          echo "::stop-commands::`echo -n ${{ github.token }} | sha256sum | head -c 64`"
          echo '::warning:: this will NOT be a warning'
          echo "::`echo -n ${{ github.token }} | sha256sum | head -c 64`::"
          echo '::warning:: this is a warning again'

Werte an die „Pre-“ (Vor-) und „Post-“ (Nach-)Aktionen senden

Mit dem Befehl save-state kannst Du Umgebungsvariablen für den Datenaustausch mit der pre:- oder post:-Aktionen Deines Workflows erzeugen. Zum Beispiel kannst Du mit der pre:-Aktion eine Datei erstellen, den Datei-Speicherort an die main:-Aktion übergeben und dann mit der post:-Aktion die Datei löschen. Alternativ kannst Du eine Datei mit der main:-Aktion erstellen, den Dateipfad an die post:-Aktion übergeben und ebenfalls mit der post:-Aktion die Datei löschen.

Wenn Du mehrere pre:- oder post:-Aktionen hast, kannst Du auf den gespeicherten Wert nur in der Aktion zugreifen, in der save-state verwendet wurde. Weitere Informationen zur post:-Aktion findest Du unter „Metadaten-Syntax für GitHub Actions“.

Der Befehl save-state kann nur innerhalb einer Aktion ausgeführt werden und ist für YAML Dateien nicht verfügbar. Der gespeicherte Wert wird als Umgebungswert mit dem Präfix STATE_ gespeichert.

Dieses Beispiel verwendet JavaScript, um den Befehl save-state auszuführen. Die resultierende Umgebungsvariable heißt STATE_processID und hat den Wert 12345:

console.log('::save-state name=processID::12345')

Die Variable STATE_processID ist dann exklusiv für das Bereinigungsskript verfügbar, das unter der main-Aktion ausgeführt wird. Dieses Beispiel läuft in main und verwendet JavaScript, um den Wert anzuzeigen, der der STATE_processID Umgebungsvariable zugewiesen wurde:

console.log("The running PID from the main action is: " +  process.env.STATE_processID);