Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.
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.
Die meisten Workflowbefehle verwenden den Befehl echo
in einem spezifischen Format, während andere durch Schreiben in eine Datei aufgerufen werden. Weitere Informationen findest du unter Umgebungsdateien.
Beispiel für einen Workflowbefehl
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"
Hinweis: Bei Workflowbefehls- und Parameternamen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
Warnung: Wenn du die Eingabeaufforderung verwendest, lasse doppelte Anführungszeichen ("
) bei Verwendung von Workflowbefehlen aus.
Workflow-Befehle verwenden, um auf Funktionen des Toolkits zuzugreifen
Die Aktionen/Toolkit enthält eine Reihe von Funktionen, die als Workflowbefehle ausgeführt werden können. Verwende die Syntax ::
, um die Workflowbefehle in deiner YAML-Datei auszuführen. Diese Befehle werden dann über stdout
an den Runner gesendet. Anstatt beispielsweise eine Ausgabe über den Code festzulegen, kannst du wie folgt vorgehen:
core.setOutput('SELECTED_COLOR', 'green');
Beispiel: Festlegen eines Werts
Du kannst den Befehl set-output
in deinem Workflow verwenden, um denselben Wert festzulegen:
- 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 }}"
- name: Set selected color
run: Write-Output "::set-output name=SELECTED_COLOR::green"
id: random-color-generator
- name: Get color
run: Write-Output "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 | Barrierefrei mithilfe der Umgebungsdatei GITHUB_PATH |
core.debug | debug |
core.notice | notice |
core.error | error |
core.endGroup | endgroup |
core.exportVariable | Barrierefrei mithilfe der Umgebungsdatei GITHUB_ENV |
core.getInput | Barrierefrei mithilfe der Umgebungsvariablen INPUT_{NAME} |
core.getState | Barrierefrei mithilfe der Umgebungsvariablen STATE_{NAME} |
core.isDebug | Barrierefrei mithilfe der Umgebungsvariablen RUNNER_DEBUG |
Festlegen eines Ausgabeparameters
Legt den Ausgabeparameter einer Aktion fest.
::set-output name={name}::{value}
Optional kannst du auch Ausgabeparameter in der Metadaten-Datei einer Aktion deklarieren. Weitere Informationen findest du unter Metadatensyntax für GitHub Actions.
Du kannst mehrzeilige Zeichenfolgen zum Festlegen eines Ausgabeparameters umgehen, indem du eine Umgebungsvariable erstellst und sie in einem Workflowbefehl verwendest. Weitere Informationen findest du unter Festlegen einer Umgebungsvariablen.
Beispiel: Festlegen eines Ausgabeparameters
echo "::set-output name=action_fruit::strawberry"
Write-Output "::set-output name=action_fruit::strawberry"
Festlegen einer Debugmeldung
Gibt eine Debugging-Meldung im Protokoll aus. Du musst einen Geheimschlüssel ACTIONS_STEP_DEBUG
mit dem Wert true
erstellen, um die Debugmeldungen anzuzeigen, die in diesem Befehl im Protokoll festgelegt sind. Weitere Informationen findest du unter Aktivieren der Debugprotokollierung.
::debug::{message}
Beispiel: Festlegen einer Debugmeldung
echo "::debug::Set the Octocat variable"
Write-Output "::debug::Set the Octocat variable"
Festlegen einer Benachrichtigung
Erstellt eine Benachrichtigung und fügt diese in das Protokoll ein. Diese Nachricht erstellt eine Anmerkung, die die Nachricht einer bestimmten Datei in deinem Repository zuordnen kann. Optional kann deine Nachricht eine Position innerhalb der Datei angeben.
::notice file={name},line={line},endLine={endLine},title={title}::{message}
Parameter | value |
---|---|
title | Benutzerdefinierter Titel |
file | Dateiname |
col | Spaltennummer ab 1 |
endColumn | Endspaltennummer |
line | Zeilennummer ab 1 |
endLine | Endzeilennummer |
Beispiel: Festlegen einer Benachrichtigung
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Festlegen einer Warnmeldung
Erstellt eine Warnmeldung und fügt die Mitteilung in das Protokoll ein. Diese Nachricht erstellt eine Anmerkung, die die Nachricht einer bestimmten Datei in deinem Repository zuordnen kann. Optional kann deine Nachricht eine Position innerhalb der Datei angeben.
::warning file={name},line={line},endLine={endLine},title={title}::{message}
Parameter | value |
---|---|
title | Benutzerdefinierter Titel |
file | Dateiname |
col | Spaltennummer ab 1 |
endColumn | Endspaltennummer |
line | Zeilennummer ab 1 |
endLine | Endzeilennummer |
Beispiel: Festlegen einer Warnmeldung
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Festlegen einer Fehlermeldung
Erstellt eine Fehlermeldung und fügt die Mitteilung in das Protokoll ein. Diese Nachricht erstellt eine Anmerkung, die die Nachricht einer bestimmten Datei in deinem Repository zuordnen kann. Optional kann deine Nachricht eine Position innerhalb der Datei angeben.
::error file={name},line={line},endLine={endLine},title={title}::{message}
Parameter | value |
---|---|
title | Benutzerdefinierter Titel |
file | Dateiname |
col | Spaltennummer ab 1 |
endColumn | Endspaltennummer |
line | Zeilennummer ab 1 |
endLine | Endzeilennummer |
Beispiel: Festlegen einer Fehlermeldung
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Gruppieren von Protokollzeilen
Erstellt eine erweiterbare Gruppe im Protokoll. Verwende den Befehl group
, um eine Gruppe zu erstellen und title
festzulegen. Alles, was du im Protokoll zwischen den group
Befehlen endgroup
einfügst, wird in einem erweiterbaren Eintrag im Protokoll geschachtelt.
::group::{title}
::endgroup::
Beispiel: Gruppieren von Protokollzeilen
jobs:
bash-example:
runs-on: ubuntu-latest
steps:
- name: Group of log lines
run: |
echo "::group::My title"
echo "Inside group"
echo "::endgroup::"
jobs:
powershell-example:
runs-on: windows-latest
steps:
- name: Group of log lines
run: |
Write-Output "::group::My title"
Write-Output "Inside group"
Write-Output "::endgroup::"
Maskieren eines Werts im Protokoll
::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 Zeichenfolge für den Wert value
der Maske verwenden. Wenn du einen Wert maskierst, wird er als geheim behandelt und auf dem Runner bearbeitet. Wenn du beispielsweise einen Wert maskierst, kannst du diesen Wert nicht als Ausgabe festlegen.
Beispiel: Maskieren einer Zeichenfolge
Wenn du im Protokoll "Mona The Octocat"
einfügst, wird "***"
angezeigt.
echo "::add-mask::Mona The Octocat"
Write-Output "::add-mask::Mona The Octocat"
Warnung: Stelle sicher, dass du das Geheimnis mit „add-mask“ registrierst, bevor es in den Buildprotokollen ausgegeben oder in anderen Workflowbefehlen verwendet wird.
Beispiel: Maskieren einer Umgebungsvariablen
Wenn du die Variable MY_NAME
oder den Wert "Mona The Octocat"
im Protokoll einfügst, wird "***"
anstelle von "Mona The Octocat"
angezeigt.
jobs:
bash-example:
runs-on: ubuntu-latest
env:
MY_NAME: "Mona The Octocat"
steps:
- name: bash-version
run: echo "::add-mask::$MY_NAME"
jobs:
powershell-example:
runs-on: windows-latest
env:
MY_NAME: "Mona The Octocat"
steps:
- name: powershell-version
run: Write-Output "::add-mask::$env:MY_NAME"
Beenden und Starten von Workflowbefehlen
Beendet die Verarbeitung von Workflowbefehlen. Mit diesem speziellen Befehl kannst du alles protokollieren, ohne versehentlich einen Workflowbefehl auszuführen. Du kannst beispielsweise die Protokollierung anhalten, um ein vollständiges Skript mit Kommentaren auszugeben.
::stop-commands::{endtoken}
Um die Verarbeitung von Workflowbefehlen zu beenden, übergib ein eindeutiges Token an stop-commands
. Um die Verarbeitung von Workflowbefehlen fortzusetzen, übergib dasselbe Token, das du zum Beenden von Workflowbefehlen verwendet hast.
Warnung: Stelle sicher, dass das verwendete Token zufällig generiert und für jede Ausführung eindeutig ist.
::{endtoken}::
Beispiel: Beenden und Starten von Workflowbefehlen
jobs:
workflow-command-job:
runs-on: ubuntu-latest
steps:
- name: Disable workflow commands
run: |
echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
stopMarker=$(uuidgen)
echo "::stop-commands::$stopMarker"
echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
echo "::$stopMarker::"
echo '::warning:: This is a warning again, because stop-commands has been turned off.'
jobs:
workflow-command-job:
runs-on: windows-latest
steps:
- name: Disable workflow commands
run: |
Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
$stopMarker = New-Guid
Write-Output "::stop-commands::$stopMarker"
Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
Write-Output "::$stopMarker::"
Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'
Echo von Befehlsausgaben
Aktiviert oder deaktiviert das Echo von Workflowbefehlen. Wenn du beispielsweise den Befehl set-output
in einem Workflow verwendest, wird ein Ausgabeparameter festgelegt, aber das Protokoll des Workflows zeigt den Befehl nicht selbst an. Wenn du das Echo von Befehlen aktivierst, zeigt das Protokoll den Befehl an, z. B. ::set-output name={name}::{value}
.
::echo::on
::echo::off
Das Echo von Befehlen ist standardmäßig deaktiviert. Wenn Fehler beim Verarbeiten eines Workflowbefehls auftreten, wird dieser als Echo zurückgegeben.
Die Befehle add-mask
, debug
, warning
und error
unterstützen das Echo nicht, da ihre Ausgaben bereits im Protokoll enthalten sind.
Du kannst das Echo von Befehlen auch global aktivieren, indem du die schrittweise Debugprotokollierung mithilfe des geheimen Schlüssels ACTIONS_STEP_DEBUG
aktivierst. Weitere Informationen findest du unter Aktivieren der Debugprotokollierung. Im Gegensatz dazu kannst du das Echo von Befehlen mit dem Workflowbefehl echo
auf einer detaillierteren Ebene aktivieren, anstatt es für jeden Workflow in einem Repository zu aktivieren.
Beispiel: Umschalten des Echos von Befehlen
jobs:
workflow-command-job:
runs-on: ubuntu-latest
steps:
- name: toggle workflow command echoing
run: |
echo '::set-output name=action_echo::disabled'
echo '::echo::on'
echo '::set-output name=action_echo::enabled'
echo '::echo::off'
echo '::set-output name=action_echo::disabled'
jobs:
workflow-command-job:
runs-on: windows-latest
steps:
- name: toggle workflow command echoing
run: |
write-output "::set-output name=action_echo::disabled"
write-output "::echo::on"
write-output "::set-output name=action_echo::enabled"
write-output "::echo::off"
write-output "::set-output name=action_echo::disabled"
Im obigen Beispiel werden die folgenden Zeilen im Protokoll ausgegeben:
::set-output name=action_echo::enabled
::echo::off
Nur die zweiten Workflowbefehle set-output
und echo
sind im Protokoll enthalten, da das Befehlsecho nur für deren Ausführung aktiviert war. Auch wenn nicht immer ein Echo erzeugt wird, wird der Ausgabeparameter in jedem Fall festgelegt.
Werte an die „Pre-“ (Vor-) und „Post-“ (Nach-)Aktionen senden
Du kannst den Befehl save-state
verwenden, um Umgebungsvariablen für die gemeinsame Nutzung mit den Aktionen pre:
oder post:
deines Workflows zu erstellen. Du kannst beispielsweise eine Datei mit der Aktion pre:
erstellen, den Dateispeicherort an die Aktion main:
übergeben und dann die Aktion post:
verwenden, um die Datei zu löschen. Alternativ kannst du eine Datei mit der Aktion main:
erstellen, den Dateispeicherort an die Aktion post:
übergeben und auch die Aktion post:
verwenden, um die Datei zu löschen.
Wenn mehrere Aktionen pre:
oder post:
vorhanden sind, kannst du nur auf den gespeicherten Wert in der Aktion zugreifen, in der save-state
verwendet wurde. Weitere Informationen zur post:
-Aktion findest du unter Metadatensyntax für GitHub Actions.
Der Befehl save-state
kann nur innerhalb einer Aktion ausgeführt werden und ist nicht für YAML-Dateien verfügbar. Der gespeicherte Wert wird als Umgebungswert mit dem Präfix STATE_
gespeichert.
In diesem Beispiel wird JavaScript zum Ausführen des Befehls save-state
verwendet. Die resultierende Umgebungsvariable wird STATE_processID
genannt und hat den Wert 12345
:
console.log('::save-state name=processID::12345')
Die Variable STATE_processID
ist dann ausschließlich für das unter der Aktion main
ausgeführte Bereinigungsskript verfügbar. Dieses Beispiel läuft in main
und verwendet JavaScript, um den Wert anzuzeigen, der der Umgebungsvariable STATE_processID
zugewiesen wurde:
console.log("The running PID from the main action is: " + process.env.STATE_processID);
Umgebungsdateien
Während der Ausführung eines Workflows generiert der Runner temporäre Dateien, die zum Ausführen bestimmter Aktionen verwendet werden können. Der Pfad zu diesen Dateien wird über Umgebungsvariablen verfügbar gemacht. Du musst UTF-8-Codierung verwenden, wenn du in diese Dateien schreibst, um die ordnungsgemäße Verarbeitung der Befehle sicherzustellen. Mehrere Befehle können in dieselbe Datei geschrieben werden, getrennt durch Zeilenvorschubzeichen.
Die meisten Befehle in den folgenden Beispielen verwenden doppelte Anführungszeichen zum Wiedergeben von Zeichenfolgen, die versuchen, Zeichen wie $
für Shellvariablennamen zu interpolieren. Um literale Werte in Zeichenfolgen in Anführungszeichen immer zu verwenden, kannst du stattdessen einzelne Anführungszeichen verwenden.
Hinweis: PowerShell-Versionen 5.1 und niedriger (shell: powershell
) verwenden standardmäßig kein UTF-8, sodass du die UTF-8-Codierung angeben musst. Beispiel:
jobs:
legacy-powershell-example:
runs-on: windows-latest
steps:
- shell: powershell
run: |
"mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
PowerShell Core-Versionen 6 und höher (shell: pwsh
) verwenden standardmäßig UTF-8. Beispiel:
jobs:
powershell-core-example:
runs-on: windows-latest
steps:
- shell: pwsh
run: |
"mypath" >> $env:GITHUB_PATH
Festlegen einer Umgebungsvariablen
echo "{environment_variable_name}={value}" >> $GITHUB_ENV
-
Bei Verwendung von PowerShell-Version 6 und höher:
pwsh "{environment_variable_name}={value}" >> $env:GITHUB_ENV
-
Bei Verwendung von PowerShell-Version 5.1 und niedriger:
powershell "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
Du kannst eine Umgebungsvariable für alle nachfolgenden Schritte in einem Workflowauftrag verfügbar machen, indem du die Umgebungsvariable definierst oder aktualisierst und diese in die Umgebungsdatei GITHUB_ENV
schreibst. Der Schritt, der die Umgebungsvariable erstellt oder aktualisiert, hat keinen Zugriff auf den neuen Wert, aber alle nachfolgenden Schritte in einem Auftrag haben Zugriff. Bei Namen von Umgebungsvariablen wird die Groß- und Kleinschreibung berücksichtigt. Du kannst darin auch Satzzeichen verwenden. Weitere Informationen findest du unter Variablen.
Beispiel für das Schreiben einer Umgebungsvariablen in GITHUB_ENV
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'
steps:
- name: Set the value
id: step_one
run: |
"action_state=yellow" >> $env:GITHUB_ENV
- name: Use the value
id: step_two
run: |
Write-Output "${{ env.action_state }}" # This will output 'yellow'
Mehrzeilige Zeichenfolgen
Bei mehrzeiligen Zeichenfolgen kannst du ein Trennzeichen mit der folgenden Syntax verwenden.
{name}<<{delimiter}
{value}
{delimiter}
Warnung: Stelle sicher, dass das verwendete Trennzeichen zufällig generiert und für jede Ausführung eindeutig ist. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions.
Beispiel für eine mehrzeilige Zeichenfolge
In diesem Beispiel wird ein zufälliger Wert für $EOF
als Trennzeichen ausgewählt und die Umgebungsvariable JSON_RESPONSE
auf den Wert der Antwort curl
festgelegt.
steps:
- name: Set the value in bash
id: step_one
run: |
EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
echo "JSON_RESPONSE<<$EOF" >> $GITHUB_ENV
curl https://example.com >> $GITHUB_ENV
echo "$EOF" >> $GITHUB_ENV
steps:
- name: Set the value in pwsh
id: step_one
run: |
-join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)}) | set EOF
"JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
(Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
"$EOF" >> $env:GITHUB_ENV
shell: pwsh
Hinzufügen eines Systempfads
Stellt ein Verzeichnis der Systemvariable PATH
vor und stellt es automatisch für alle nachfolgenden Aktionen im aktuellen Auftrag zur Verfügung. Die aktuell ausgeführte Aktion kann nicht auf die aktualisierte Pfadvariable zugreifen. Um die aktuell definierten Pfade für deinen Auftrag anzuzeigen, kannst du in einem Schritt oder einer Aktion echo "$PATH"
verwenden.
echo "{path}" >> $GITHUB_PATH
"{path}" >> $env:GITHUB_PATH
Beispiel für das Hinzufügen eines Systempfads
In diesem Beispiel wird veranschaulicht, wie du das Benutzerverzeichnis $HOME/.local/bin
zu PATH
hinzufügst:
echo "$HOME/.local/bin" >> $GITHUB_PATH
In diesem Beispiel wird veranschaulicht, wie du das Benutzerverzeichnis $env:HOMEPATH/.local/bin
zu PATH
hinzufügst:
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH