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

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

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

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

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

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

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: color-selector
      - name: Get color

        run: echo "The selected color is ${{ steps.color-selector.outputs.SELECTED_COLOR }}"

      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: color-selector
      - name: Get color

        run: echo "The selected color is ${{ steps.color-selector.outputs.SELECTED_COLOR }}"

      - name: Set selected color
        run: Write-Output "::set-output name=SELECTED_COLOR::green"
        id: color-selector
      - name: Get color

        run: Write-Output "The selected color is ${{ steps.color-selector.outputs.SELECTED_COLOR }}"

      - name: Set selected color
        run: Write-Output "::set-output name=SELECTED_COLOR::green"
        id: color-selector
      - name: Get color

        run: Write-Output "The selected color is ${{ steps.color-selector.outputs.SELECTED_COLOR }}"

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

Festlegen eines Ausgabeparameters

Legt den Ausgabeparameter einer Aktion fest.

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

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

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

Write-Output "::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}

::debug::{message}

Beispiel: Festlegen einer Debugmeldung

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

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

Write-Output "::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}

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

Beispiel: Festlegen einer Benachrichtigung

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

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"

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}

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

Beispiel: Festlegen einer Warnmeldung

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

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"

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}

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

Beispiel: Festlegen einer Fehlermeldung

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

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"

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

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

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 in einem Protokoll

::add-mask::{value}

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

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

Write-Output "::add-mask::Mona The Octocat"

Write-Output "::add-mask::Mona The Octocat"

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

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"

Beispiel: Maskieren einer generierten Ausgabe innerhalb eines einzelnen Auftrags

Wenn du dein Geheimnis nicht von einem Auftrag an einen anderen Auftrag übergeben musst, hast du folgende Möglichkeiten:

1. Generiere das Geheimnis (ohne es auszugeben).

2. Maskiere es mit add-mask.

3. Verwende set-output, um das Geheimnis für andere Schritte innerhalb des Auftrags verfügbar zu machen.

on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        run: |
          the_secret=$((RANDOM))
          echo "::add-mask::$the_secret"
          echo "::set-output name=secret-number::$the_secret"
      - name: Use that secret output (protected by a mask)
        run: |
          echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        run: |
          the_secret=$((RANDOM))
          echo "::add-mask::$the_secret"
          echo "::set-output name=secret-number::$the_secret"
      - name: Use that secret output (protected by a mask)
        run: |
          echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        shell: pwsh
        run: |
          Set-Variable -Name TheSecret -Value (Get-Random)
          Write-Output "::add-mask::$TheSecret"
          Write-Output "::set-output name=secret-number::$TheSecret"
      - name: Use that secret output (protected by a mask)
        shell: pwsh
        run: |
          Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

on: push
jobs:
  generate-a-secret-output:
    runs-on: ubuntu-latest
    steps:
      - id: sets-a-secret
        name: Generate, mask, and output a secret
        shell: pwsh
        run: |
          Set-Variable -Name TheSecret -Value (Get-Random)
          Write-Output "::add-mask::$TheSecret"
          Write-Output "::set-output name=secret-number::$TheSecret"
      - name: Use that secret output (protected by a mask)
        shell: pwsh
        run: |
          Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"

Beispiel: Maskieren und Übergeben eines Geheimnisses zwischen Aufträgen oder Workflows

Wenn du ein maskiertes Geheimnis zwischen Aufträgen oder Workflows übergeben möchtest, solltest du das Geheimnis in einem Speicher speichern und dann im nachfolgenden Auftrag oder Workflow abrufen.

Einrichten

1. Richte einen Geheimnisspeicher ein, um das Geheimnis zu speichern, das du während deines Workflows generierst. Beispiel: Tresor.
2. Generiere einen Schlüssel zum Lesen und Schreiben in diesem Geheimspeicher. Speichere den Schlüssel als Repositorygeheimnis. Im folgenden Beispielworkflow lautet der Geheimnisname SECRET_STORE_CREDENTIALS. Weitere Informationen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

Workflow

on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    outputs:
      handle: ${{ steps.generate-secret.outputs.handle }}
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      id: generate-secret
      shell: bash
      run: |
        GENERATED_SECRET=$((RANDOM))
        echo "::add-mask::$GENERATED_SECRET"
        SECRET_HANDLE=$(secret-store store-secret "$GENERATED_SECRET")
        echo "::set-output name=handle::$SECRET_HANDLE"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: bash
      run: |
        SECRET_HANDLE="${{ needs.secret-generator.outputs.handle }}"
        RETRIEVED_SECRET=$(secret-store retrieve-secret "$SECRET_HANDLE")
        echo "::add-mask::$RETRIEVED_SECRET"
        echo "We retrieved our masked secret: $RETRIEVED_SECRET"

on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    outputs:
      handle: ${{ steps.generate-secret.outputs.handle }}
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      id: generate-secret
      shell: bash
      run: |
        GENERATED_SECRET=$((RANDOM))
        echo "::add-mask::$GENERATED_SECRET"
        SECRET_HANDLE=$(secret-store store-secret "$GENERATED_SECRET")
        echo "::set-output name=handle::$SECRET_HANDLE"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: bash
      run: |
        SECRET_HANDLE="${{ needs.secret-generator.outputs.handle }}"
        RETRIEVED_SECRET=$(secret-store retrieve-secret "$SECRET_HANDLE")
        echo "::add-mask::$RETRIEVED_SECRET"
        echo "We retrieved our masked secret: $RETRIEVED_SECRET"

on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: pwsh
      run: |
        Set-Variable -Name Generated_Secret -Value (Get-Random)
        Write-Output "::add-mask::$Generated_Secret"
        Set-Variable -Name Secret_Handle -Value (Store-Secret "$Generated_Secret")
        Write-Output "::set-output name=handle::$Secret_Handle"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: pwsh
      run: |
        Set-Variable -Name Secret_Handle -Value "${{ needs.secret-generator.outputs.handle }}"
        Set-Variable -Name Retrieved_Secret -Value (Retrieve-Secret "$Secret_Handle")
        echo "::add-mask::$Retrieved_Secret"
        echo "We retrieved our masked secret: $Retrieved_Secret"

on: push

jobs:
  secret-generator:
    runs-on: ubuntu-latest
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: generate secret
      shell: pwsh
      run: |
        Set-Variable -Name Generated_Secret -Value (Get-Random)
        Write-Output "::add-mask::$Generated_Secret"
        Set-Variable -Name Secret_Handle -Value (Store-Secret "$Generated_Secret")
        Write-Output "::set-output name=handle::$Secret_Handle"
  secret-consumer:
    runs-on: macos-latest
    needs: secret-generator
    steps:
    - uses: some/secret-store@v1
      with:
        credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }}
        instance: ${{ secrets.SECRET_STORE_INSTANCE }}
    - name: use secret
      shell: pwsh
      run: |
        Set-Variable -Name Secret_Handle -Value "${{ needs.secret-generator.outputs.handle }}"
        Set-Variable -Name Retrieved_Secret -Value (Retrieve-Secret "$Secret_Handle")
        echo "::add-mask::$Retrieved_Secret"
        echo "We retrieved our masked secret: $Retrieved_Secret"

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}

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

::{endtoken}::

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

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

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

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

::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')

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

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.

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

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" | Out-File -FilePath $env:GITHUB_PATH -Append

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

Festlegen einer Umgebungsvariablen

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

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

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.

Du kannst den Wert der Standardumgebungsvariablen namens GITHUB_* und RUNNER_* nicht überschreiben. Derzeit kannst du den Wert der Variablen CI überschreiben. Es ist jedoch nicht garantiert, dass dies immer möglich sein wird. Weitere Informationen zu den Standard-Umgebungsvariablen finden Sie 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: |
      printf '%s\n' "$action_state" # This will output 'yellow'

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

steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" | Out-File -FilePath $env:GITHUB_ENV -Append
  - name: Use the value
    id: step_two
    run: |
      Write-Output "$env:action_state" # This will output 'yellow'

steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" | Out-File -FilePath $env:GITHUB_ENV -Append
  - 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}

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

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 bash
    id: step_one
    run: |
      {
        echo 'JSON_RESPONSE<<EOF'
        curl https://example.com
        echo EOF
      } >> "$GITHUB_ENV"

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

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      $EOF = -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)})
      "JSON_RESPONSE<<$EOF" | Out-File -FilePath $env:GITHUB_ENV -Append
      (Invoke-WebRequest -Uri "https://example.com").Content | Out-File -FilePath $env:GITHUB_ENV -Append
      "$EOF" | Out-File -FilePath $env:GITHUB_ENV -Append
    shell: pwsh

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      $EOF = -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)})
      "JSON_RESPONSE<<$EOF" | Out-File -FilePath $env:GITHUB_ENV -Append
      (Invoke-WebRequest -Uri "https://example.com").Content | Out-File -FilePath $env:GITHUB_ENV -Append
      "$EOF" | Out-File -FilePath $env:GITHUB_ENV -Append
    shell: pwsh

Hinzufügen einer Auftragszusammenfassung

echo "{markdown content}" >> $GITHUB_STEP_SUMMARY

echo "{markdown content}" >> $GITHUB_STEP_SUMMARY

"{markdown content}" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append

"{markdown content}" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append

Du kannst ein benutzerdefiniertes Markdown für die einzelnen Aufträge festlegen, sodass sie auf der Zusammenfassungsseite einer Workflowausführung angezeigt werden. Du kannst Auftragszusammenfassungen verwenden, um eindeutige Inhalte (z. B. Zusammenfassungen von Testergebnissen) anzuzeigen und zu gruppieren, damit Personen, die das Ergebnis einer Workflowausführung anzeigen, nicht in die Protokolle wechseln müssen, um wichtige ausführungsbezogene Informationen (z. B. Fehler) anzuzeigen.

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. Wenn für mehrere Aufträge Zusammenfassungen generiert werden, werden diese nach Auftragsabschlusszeit sortiert.

Beispiel für das Hinzufügen einer Auftragszusammenfassung

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

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

"### Hello world! :rocket:" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append

"### Hello world! :rocket:" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append

Mehrzeiliger Markdowninhalt

Für mehrzeiligen Markdowninhalt kannst du mit >> kontinuierlich Inhalte für den aktuellen Schritt anfügen. Bei jedem Anfügevorgang wird automatisch ein Zeilenvorschubzeichen hinzugefügt.

Beispiel für mehrzeiligen Markdowninhalt

- 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

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

Überschreiben von Auftragszusammenfassungen

Zum Löschen aller Inhalte für den aktuellen Schritt können Sie > verwenden, um alle zuvor hinzugefügten Inhalte in der Bash zu überschreiben, oder -Append in der PowerShell entfernen

Beispiel für das Ü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

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

Entfernen von Auftragszusammenfassungen

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: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY

- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append
    Remove-Item $env:GITHUB_STEP_SUMMARY

Nachdem ein Schritt abgeschlossen wurde, werden Auftragszusammenfassungen hochgeladen, und zuvor hochgeladene Markdowninhalte können durch nachfolgende Schritte nicht geändert werden. 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 Eine Workflowausführung löschen.

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

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

echo "{path}" >> $GITHUB_PATH

"{path}" | Out-File -FilePath $env:GITHUB_PATH -Append

"{path}" | Out-File -FilePath $env:GITHUB_PATH -Append

Beispiel für das Hinzufügen eines Systempfads

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

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

"$env:HOMEPATH/.local/bin" | Out-File -FilePath $env:GITHUB_PATH -Append

"$env:HOMEPATH/.local/bin" | Out-File -FilePath $env:GITHUB_PATH -Append