Workflow commands for GitHub Actions

Workflow commands for GitHub Actions (Workflowbefehle für GitHub Actions)

Workflowbefehle

Du kannst Workflow-Befehle verwenden, wenn du Shell-Befehle in einem Workflow oder im Code einer Aktion ausführst.

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.

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

Weitere Informationen findest du unter Umgebungsdateien.

Beispiel für einen Workflowbefehl

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

Warnung: Wenn du die Eingabeaufforderung verwendest, lasse doppelte Anführungszeichen (") bei Verwendung von Workflowbefehlen aus.

Workflow-Befehle verwenden, um auf Funktionen des Toolkits zuzugreifen

core.error('Missing semicolon', {file: 'app.js', startLine: 1})

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 Fehleranmerkung über den Code zu erstellen, kannst du wie folgt vorgehen:

Beispiel: Erstellen einer Anmerkung zu einem Fehler

      - name: Create annotation for build error
        run: echo "::error file=app.js,line=1::Missing semicolon"

Du kannst den Befehl error in deinem Workflow verwenden, um dieselbe Fehleranmerkung zu erstellen:

      - name: Create annotation for build error
        run: Write-Output "::error file=app.js,line=1::Missing semicolon"

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

Barrierefrei mithilfe der Umgebungsvariablen STATE_{NAME}

Barrierefrei mithilfe der Umgebungsvariablen RUNNER_DEBUG | core.summary | Barrierefrei mithilfe der Umgebungsdatei GITHUB_STEP_SUMMARY | | core.saveState | Barrierefrei mithilfe der Umgebungsdatei GITHUB_STATE | | core.setCommandEcho | echo | | core.setFailed | Wird als Abkürzung für ::error und exit 1 verwendet | | core.setOutput | Barrierefrei mithilfe der Umgebungsdatei GITHUB_OUTPUT | | core.setSecret | add-mask | | core.startGroup | group | | core.warning | warning |

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

Festlegen einer Debugmeldung

::debug::{message}

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.

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

Weitere Informationen findest du unter Aktivieren der Debugprotokollierung.

Beispiel: Festlegen einer Debugmeldung

Write-Output "::debug::Set the Octocat variable"

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

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.

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

Beispiel: Festlegen einer Benachrichtigung

Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

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

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.

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

Beispiel: Festlegen einer Warnmeldung

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

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

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.

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

Beispiel: Festlegen einer Fehlermeldung

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

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

Erstellt eine erweiterbare Gruppe im Protokoll.

Verwende den Befehl group, um eine Gruppe zu erstellen und title festzulegen.

jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"

Alles, was du im Protokoll zwischen den group Befehlen endgroup einfügst, wird in einem erweiterbaren Eintrag im Protokoll geschachtelt.

Beispiel: Gruppieren von Protokollzeilen

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::"

::add-mask::{value}

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.

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

Beispiel: Maskieren einer Zeichenfolge

Wenn du im Protokoll "Mona The Octocat" einfügst, wird "***" angezeigt.

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.

jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"

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:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"

::stop-commands::{endtoken}

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.

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.

::{endtoken}::

Warnung: Stelle sicher, dass das verwendete Token zufällig generiert und für jede Ausführung eindeutig ist.

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.'

Beispiel: Beenden und Starten von Workflowbefehlen

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.'

Du kannst Umgebungsvariablen für die gemeinsame Nutzung mit den Aktionen pre: oder post: deines Workflows erstellen, indem du in die Datei unter GITHUB_STATE schreibst. 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 der Wert in GITHUB_STATE geschrieben wurde.

Weitere Informationen zur Aktion post: findest du unter Metadatensyntax für GitHub Actions. Die Datei GITHUB_STATE ist nur innerhalb einer Aktion verfügbar.

import * as fs from 'fs'
import * as os from 'os'

fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, {
  encoding: 'utf8'
})

Der gespeicherte Wert wird als Umgebungswert mit dem Präfix STATE_ gespeichert. In diesem Beispiel wird JavaScript verwendet, um in die Datei GITHUB_STATE zu schreiben.

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

Die resultierende Umgebungsvariable wird STATE_processID genannt und hat den Wert 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: 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.

jobs:
  legacy-powershell-example:
    runs-on: windows-latest
    steps:
      - shell: powershell
        run: |
          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

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

Festlegen einer Umgebungsvariablen

• pwsh

  "{environment_variable_name}={value}" >> $env:GITHUB_ENV

• powershell

  "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append

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 Umgebungsvariablen.

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

Beispiel für das Schreiben einer Umgebungsvariablen in GITHUB_ENV

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 "$" # This will output 'yellow'

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

Mehrzeilige Zeichenfolgen Bei mehrzeiligen Zeichenfolgen kannst du ein Trennzeichen mit der folgenden Syntax verwenden.

steps:
  - name: Set the value in bash
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV

Beispiel für eine mehrzeilige Zeichenfolge

In diesem Beispiel wird EOF als Trennzeichen verwendet und die Umgebungsvariable JSON_RESPONSE auf den Wert der Antwort curl festgelegt.

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      "JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "EOF" >> $env:GITHUB_ENV
    shell: pwsh

Festlegen eines Ausgabeparameters

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

Legt den Ausgabeparameter eines Schritts fest.

Beachte, dass für den Schritt eine id definiert werden muss, um später den Ausgabewert abzurufen.

"{name}=value" >> $env:GITHUB_OUTPUT

Beispiel für das Festlegen eines Ausgabeparameters

      - name: Set color
        id: random-color-generator
        run: echo "SELECTED_COLOR=green" >> $GITHUB_OUTPUT
      - name: Get color
        run: echo "The selected color is $"

      - name: Set color
        id: random-color-generator
        run: |
            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
      - name: Get color
        run: Write-Output "The selected color is $"

echo "{markdown content}" >> $GITHUB_STEP_SUMMARY

Hinzufügen einer Auftragszusammenfassung

"{markdown content}" >> $env:GITHUB_STEP_SUMMARY

Auftragszusammenfassungen unterstützen GitHub-Markdown, und du kannst der GITHUB_STEP_SUMMARY-Umgebungsdatei eigenen Markdowninhalt für einen Schritt hinzufügen. GITHUB_STEP_SUMMARY ist für jeden Schritt in einem Auftrag eindeutig.

Weitere Informationen zu der Pro-Schritt-Datei, auf die GITHUB_STEP_SUMMARY verweist, findest du unter „Umgebungsdateien“.

Bei Abschluss eines Auftrags werden die Zusammenfassungen für alle Schritte in einem Auftrag in einer einzelnen Auftragszusammenfassung gruppiert und auf der Zusammenfassungsseite der Workflowausführung angezeigt.

echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY

Wenn für mehrere Aufträge Zusammenfassungen generiert werden, werden diese nach Auftragsabschlusszeit sortiert.

Beispiel für das Hinzufügen einer Auftragszusammenfassung

"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY

Mehrzeiliger Markdowninhalt

Für mehrzeiligen Markdowninhalt kannst du mit >> kontinuierlich Inhalte für den aktuellen Schritt anfügen.

- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY

Bei jedem Anfügevorgang wird automatisch ein Zeilenvorschubzeichen hinzugefügt.

Beispiel für mehrzeiligen Markdowninhalt

- name: Generate list using Markdown
  run: |
    "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY
    "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line
    "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY

Überschreiben von Auftragszusammenfassungen

- name: Overwrite Markdown
  run: |
    echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY
    echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY

Zum Löschen aller Inhalte für den aktuellen Schritt kannst du mit > alle zuvor hinzugefügten Inhalte überschreiben.

Beispiel für das Überschreiben von Auftragszusammenfassungen

- name: Overwrite Markdown
  run: |
    "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY
    "There was an error, we need to clear the previous Markdown with some new content." > $env:GITHUB_STEP_SUMMARY

Entfernen von Auftragszusammenfassungen

- name: Delete all summary content
  run: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY

Zum vollständigen Entfernen einer Zusammenfassung für den aktuellen Schritt kannst du die Datei löschen, auf die GITHUB_STEP_SUMMARY verweist.

Beispiel für das Entfernen von Auftragszusammenfassungen

- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
    rm $env:GITHUB_STEP_SUMMARY

Alle Geheimnisse, die versehentlich hinzugefügt wurden, werden von Zusammenfassungen automatisch maskiert.

Wenn eine Auftragszusammenfassung vertrauliche Informationen enthält, die gelöscht werden müssen, kannst du die gesamte Workflowausführung löschen, um alle zugehörigen Auftragszusammenfassungen zu entfernen. Weitere Informationen findest du unter „Löschen einer Workflowausführung“. Schrittisolierung und Grenzwerte Auftragszusammenfassungen werden zwischen Schritten isoliert und jeder Schritt ist auf eine maximale Größe von 1 MiB beschränkt. Die Isolation wird zwischen Schritten erzwungen, damit das Markdownrendering für nachfolgende Schritte nicht durch potenziell fehlerhaftes Markdown unterbrochen werden kann.

Wenn für einen Schritt Inhalte von mehr als 1 MiB hinzugefügt werden, schlägt der Upload für den Schritt fehl, und es wird eine Fehleranmerkung erstellt.

Uploadfehler bei Auftragszusammenfassungen wirken sich nicht auf den Gesamtstatus eines Schritts oder Auftrags aus.

Pro Auftrag werden maximal 20 Auftragszusammenfassungen aus Schritten angezeigt.

Hinzufügen eines Systempfads

echo "{path}" >> $GITHUB_PATH

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.

"{path}" >> $env:GITHUB_PATH

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

Beispiel für das Hinzufügen eines Systempfads

"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH