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.

Most workflow commands use the echo command in a specific format, while others are invoked by writing to a file. For more information, see "Environment files".

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:

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"

Setting a debug message

::debug::{message}

Gibt eine Debugging-Meldung im Protokoll aus. Sie müssen ein Geheimnis mit dem Namen ACTIONS_STEP_DEBUG und dem Wert true erstellen, um die durch diesen Befehl festgelegten 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},col={col}::{message}

Erstellt eine Warnmeldung und fügt die Mitteilung in das Protokoll ein. Optional können Sie einen Dateinamen (file), eine Zeilennummer (line) und eine Spaltennummer (col) angeben, bei der die Warnung angezeigt wurde.

Beispiel

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

Setting an error message

::error file={name},line={line},col={col}::{message}

Erstellt eine Fehlermeldung und fügt die Mitteilung in das Protokoll ein. Optional können Sie einen Dateinamen (file), eine Zeilennummer (line) und eine Spaltennummer (col) angeben, bei der die Warnung angezeigt wurde.

Beispiel

echo "::error file=app.js,line=10,col=15::Something went wrong"

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. Sie können eine Umgebungsvariable oder einen String für den Wert (value) der Maske verwenden.

Beispiel für das Maskieren eines Strings

Wenn Sie "Mona The Octocat" im Protokoll ausgeben, sehen Sie "***".

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

Beispiel für das Maskieren einer Umgebungsvariablen

Wenn Sie die Variable MY_NAME oder den Wert "Mona The Octocat" im Protokoll ausgeben, sehen Sie "***" 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. Sie können beispielsweise die Protokollierung anhalten, um ein vollständiges Skript mit Kommentaren auszugeben.

Beispiel zum Anhalten von Workflow-Befehlen

echo "::stop-commands::pause-logging"

To start workflow commands, pass the token that you used to stop workflow commands.

::{endtoken}::

Beispiel zum Starten von Workflow-Befehlen

echo "::pause-logging::"

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);

Environment Files

During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files are exposed via environment variables. You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines.

steps:
  - run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

Setting an environment variable

echo "{name}={value}" >> $GITHUB_ENV

Erstellt oder aktualisiert eine Umgebungsvariable für alle Aktionen, die als nächstes in einem Auftrag ausgeführt werden. Die Aktion, die die Umgebungsvariable erstellt oder aktualisiert, kann nicht auf den neuen Wert zugreifen; alle nachfolgenden Aktionen in einem Auftrag haben dagegen Zugriff auf den neuen Wert. Bei Umgebungsvariablen wird die Groß- und Kleinschreibung berücksichtigt. Sie können auch Satzzeichen enthalten.

Beispiel

steps:
  - name: Set the value
    id: step_one
    run: |
        echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
        echo "${{ env.action_state }}" # This will output 'yellow'

Multiline strings

For multiline strings, you may use a delimiter with the following syntax.

{name}<<{delimiter}
{value}
{delimiter}

Beispiel

In this example, we use EOF as a delimiter and set the JSON_RESPONSE environment variable to the value of the curl response.

steps:
  - name: Set the value
    id: step_one
    run: |
        echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
        curl https://httpbin.org/json >> $GITHUB_ENV
        echo 'EOF' >> $GITHUB_ENV

Adding a system path

echo "{path}" >> $GITHUB_PATH

Prepends a directory to the system PATH variable and makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. To see the currently defined paths for your job, you can use echo "$PATH" in a step or an action.

Beispiel

This example demonstrates how to add the user $HOME/.local/bin directory to PATH:

echo "$HOME/.local/bin" >> $GITHUB_PATH