Zugreifen auf kontextbezogene Informationen zu Workflowausführungen

Informationen zu Kontexten

Kontexte sind eine Möglichkeit, auf Informationen zu Workflowausführungen, Variablen, Runnerumgebungen, Aufträge und Schritten zuzugreifen. Ein Kontext ist ein Objekt, das Eigenschaften enthält. Dabei kann es sich um Zeichenfolgen oder andere Objekte handeln.

Kontexte, Objekte und Eigenschaften variieren bei verschiedenen Workflowausführungsbedingungen erheblich. Der Kontext matrix wird beispielsweise nur für Aufträge in einer Matrix aufgefüllt.

Mithilfe der Syntax für Ausdrücke können Sie auf Kontexte zugreifen. Weitere Informationen finden Sie unter Auswerten von Ausdrücken in Workflows und Aktionen.

${{ <context> }}

Als Teil eines Ausdrucks können Sie mit einer der beiden folgenden Syntaxarten auf Kontextinformationen zugreifen.

• Indexsyntax: github['sha']
• Syntax zur Dereferenzierung von Eigenschaften: github.sha

Um die Syntax zur Dereferenzierung von Eigenschaften zu verwenden, muss der Eigenschaftsname mit einem Buchstaben oder _ beginnen oder nur alphanumerische Zeichen, - oder _ enthalten.

Wenn Sie versuchen, eine nicht vorhandene Eigenschaft zu dereferenzieren, wird sie als leere Zeichenfolge ausgewertet.

Anwendungsfälle für Kontexte

GitHub Actions enthält eine Sammlung von Variablen namens Kontexte und eine ähnliche Sammlung von Variablen namens Standardvariablen. Umgebungsvariablen und Kontexte sind für verschiedene Stellen im Workflow vorgesehen:

• Standardumgebungsvariablen: Diese Umgebungsvariablen sind nur auf dem Runner vorhanden, der deinen Auftrag ausführt. Weitere Informationen finden Sie unter Speichern von Informationen in Variablen.
• Kontexte: Du kannst die meisten Kontexte an einem beliebigen Punkt in deinem Workflow verwenden, einschließlich wenn Standardvariablen nicht verfügbar sind. Du kannst beispielsweise Kontexte mit Ausdrücken verwenden, um die anfängliche Verarbeitung auszuführen, bevor der Auftrag zur Ausführung an einen Runner weitergeleitet wird; dadurch kannst du einen Kontext mit dem bedingten if-Schlüsselwort verwenden, um festzustellen, ob ein Schritt ausgeführt werden soll. Sobald der Auftrag ausgeführt wird, kannst du auch Kontextvariablen aus dem Runner abrufen, der den Auftrag ausführt, so wie runner.os. Ausführliche Informationen dazu, wo Sie bestimmte Kontexte innerhalb eines Workflows verwenden können, finden Sie unter „Kontextverfügbarkeit“.

Im folgenden Beispiel wird veranschaulicht, wie diese verschiedenen Variablentypen in einem Auftrag zusammen verwendet werden können:

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

In diesem Beispiel überprüft die if-Anweisung den Kontext, um den github.ref aktuellen Zweignamen zu ermitteln; wenn der Name refs/heads/main lautet, werden die nachfolgenden Schritte ausgeführt. Die if-Überprüfung wird von GitHub Actions verarbeitet und der Auftrag wird nur an den Runner gesendet, wenn das Ergebnis true ist. Sobald der Auftrag an den Runner gesendet wird, wird der Schritt ausgeführt und verweist auf die $GITHUB_REF-Variable des Runners.

Kontextverfügbarkeit

Bei der Ausführung eines Workflows stehen verschiedene Kontexte zur Verfügung. Der secrets-Kontext kann beispielsweise nur an bestimmten Stellen innerhalb eines Auftrags verwendet werden.

Darüber hinaus können auch einige Funktionen nur an bestimmten Stellen verwendet werden. Die Funktion hashFiles ist beispielsweise nicht überall verfügbar.

Die folgende Tabelle enthält die Einschränkungen dafür, an welchen Stellen die einzelnen Kontexte und Sonderfunktionen innerhalb eines Workflows verwendet werden können. Die aufgeführten Kontexte stehen nur für den angegebenen Workflowschlüssel zur Verfügung und werden möglicherweise nicht an anderer Stelle verwendet. Funktionen, die nicht in der Liste aufgeführt werden, können überall verwendet werden.

Beispiel: Drucken von Kontextinformationen ins Protokoll

Sie können den Inhalt von Kontexten zum Debuggen ins Protokoll drucken. Die Funktion toJSON ist für die Quelltextformatierung von JSON-Objekten im Protokoll erforderlich

name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

Kontext github

Der github-Kontext enthält Informationen zur Workflowausführung und zum Ereignis, das die Ausführung ausgelöst hat. Die meisten Daten zum github-Kontext können Sie auch in Umgebungsvariablen lesen. Weitere Informationen zu Umgebungsvariablen finden Sie unter Speichern von Informationen in Variablen.

Beispielinhalt des github-Kontexts

Der folgende Beispielkontext stammt aus einer Workflowausführung, die vom Ereignis push ausgelöst wurde. Das event-Objekt in diesem Beispiel wurde gekürzt, da es mit dem Inhalt der Webhooknutzlast push identisch ist.

{
  "token": "***",
  "job": "dump_contexts_to_log",
  "ref": "refs/heads/my_branch",
  "sha": "c27d339ee6075c1f744c5d4b200f7901aad2c369",
  "repository": "octocat/hello-world",
  "repository_owner": "octocat",
  "repositoryUrl": "git://github.com/octocat/hello-world.git",
  "run_id": "1536140711",
  "run_number": "314",
  "retention_days": "90",
  "run_attempt": "1",
  "actor": "octocat",
  "workflow": "Context testing",
  "head_ref": "",
  "base_ref": "",
  "event_name": "push",
  "event": {
    ...
  },
  "server_url": "https://github.com",
  "api_url": "https://api.github.com",
  "graphql_url": "https://api.github.com/graphql",
  "ref_name": "my_branch",
  "ref_protected": false,
  "ref_type": "branch",
  "secret_source": "Actions",
  "workspace": "/home/runner/work/hello-world/hello-world",
  "action": "github_step",
  "event_path": "/home/runner/work/_temp/_github_workflow/event.json",
  "action_repository": "",
  "action_ref": "",
  "path": "/home/runner/work/_temp/_runner_file_commands/add_path_b037e7b5-1c88-48e2-bf78-eaaab5e02602",
  "env": "/home/runner/work/_temp/_runner_file_commands/set_env_b037e7b5-1c88-48e2-bf78-eaaab5e02602"
}

Beispielverwendung des github-Kontexts

In diesem Beispielworkflow wird der github.event_name-Kontext verwendet, um einen Auftrag nur dann auszuführen, wenn die Workflowausführung vom Ereignis pull_request ausgelöst wurde.

name: Run CI
on: [push, pull_request]

jobs:
  normal_ci:
    runs-on: ubuntu-latest
    steps:
      - name: Run normal CI
        run: echo "Running normal CI"

  pull_request_ci:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - name: Run PR CI
        run: echo "Running PR only CI"

name: Run CI
on: [push, pull_request]

jobs:
  normal_ci:
    runs-on: ubuntu-latest
    steps:
      - name: Run normal CI
        run: echo "Running normal CI"

  pull_request_ci:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - name: Run PR CI
        run: echo "Running PR only CI"

Kontext env

Der env-Kontext enthält Variablen, die in einem Workflow, Auftrag oder Schritt festgelegt wurden. Er enthält keine Variablen, die vom Runner-Prozess geerbt werden. Weitere Informationen zum Festlegen von Variablen in deinem Workflow finden Sie unter "Workflowsyntax für GitHub Actions."

Sie können die Werte von Variablen abrufen, die im env -Kontext gespeichert sind, und diese Werte in Ihrer Workflowdatei verwenden. Sie können den env-Kontext im Wert eines beliebigen Schlüssels in einem Schritt verwenden, mit Ausnahme der Schlüssel id und uses. Weitere Informationen zur Schrittsyntax finden Sie unter "Workflowsyntax für GitHub Actions."

Wenn Sie den Wert einer Variablen innerhalb eines Runners verwenden möchten, dann verwenden Sie die übliche Methode des Runner-Betriebssystems zum Lesen von Umgebungsvariablen.

Beispielinhalt des env-Kontexts

Der Inhalt des env-Kontexts ist eine Zuordnung der Variablennamen zu ihren Werten. Je nach der Stelle in der Workflowausführung kann der Inhalt des Kontexts variieren. In diesem Beispiel enthält derenv-Kontext zwei Variablen.

{
  "first_name": "Mona",
  "super_duper_var": "totally_awesome"
}

Beispielverwendung des env-Kontexts

Dieser Beispielworkflow zeigt Variablen, die im env-Kontext auf Workflow-, Auftrags- und Schrittebene festgelegt werden. Die ${{ env.VARIABLE-NAME }}-Syntax wird dann zum Abrufen von Variablenwerten innerhalb einzelner Schritte im Workflow verwendet.

Wenn mehr als eine Umgebungsvariable mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Variable. Beispielsweise setzt eine in einem Schritt definierte Umgebungsvariable Auftrags- und Workflowumgebungsvariablen mit demselben Namen außer Kraft, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Umgebungsvariable setzt eine Workflowvariable mit demselben Namen außer Kraft, während der Auftrag ausgeführt wird.

name: Hi Mascot
on: push
env:
  mascot: Mona
  super_duper_var: totally_awesome

jobs:
  windows_job:
    runs-on: windows-latest
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Mona
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Octocat
        env:
          mascot: Octocat
  linux_job:
    runs-on: ubuntu-latest
    env:
      mascot: Tux
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Tux

name: Hi Mascot
on: push
env:
  mascot: Mona
  super_duper_var: totally_awesome

jobs:
  windows_job:
    runs-on: windows-latest
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Mona
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Octocat
        env:
          mascot: Octocat
  linux_job:
    runs-on: ubuntu-latest
    env:
      mascot: Tux
    steps:
      - run: echo 'Hi ${{ env.mascot }}'  # Hi Tux

Kontext vars

Der vars-Kontext enthält benutzerdefinierte Konfigurationsvariablen, die auf Organisations-, Repository- und Umgebungsebene festgelegt sind. Weitere Informationen zum Definieren von Konfigurationsvariablen für die Verwendung in mehreren Workflows finden Sie unter Speichern von Informationen in Variablen.

Beispielinhalt des vars-Kontexts

Der Inhalt des vars-Kontexts ist eine Zuordnung der Namen von Konfigurationsvariablen zu ihren Werten.

{
  "mascot": "Mona"
}

Beispielverwendung des vars-Kontexts

Dieser Beispielworkflow zeigt, wie Konfigurationsvariablen, die auf Repository-, Umgebungs- oder Organisationsebene festgelegt werden, automatisch über den vars-Kontext verfügbar sind.

Wenn keine Konfigurationsvariable festgelegt wurde, ist der Rückgabewert eines Kontexts, der auf die Variable verweist, eine leere Zeichenfolge.

Das folgende Beispiel zeigt die Verwendung von Konfigurationsvariablen mit dem Kontext vars in einem Workflow. Jede der folgenden Konfigurationsvariablen wurde auf Repository-, Organisations- oder Umgebungsebene definiert.

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : $REPOSITORY_VAR"
        echo "organization variable : $ORGANIZATION_VAR"
        echo "overridden variable : $OVERRIDE_VAR"
        echo "variable from shell environment : $env_var"
      env:
        REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
        ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
        OVERRIDE_VAR: ${{ vars.OVERRIDE_VAR }}
        
    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

Kontext job

Der job-Kontext enthält Informationen zum derzeit ausgeführten Auftrag.

Beispielinhalt des job-Kontexts

In diesem job-Beispielkontext wird ein PostgreSQL-Dienstcontainer mit zugeordneten Ports verwendet. Werden in einem Auftrag keine Container oder Dienstcontainer verwendet, enthält der job-Kontext nur die Eigenschaft status.

{
  "status": "success",
  "container": {
    "network": "github_network_53269bd575974817b43f4733536b200c"
  },
  "services": {
    "postgres": {
      "id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105",
      "ports": {
        "5432": "49153"
      },
      "network": "github_network_53269bd575974817b43f4733536b200c"
    }
  }
}

Beispielverwendung des job-Kontexts

In diesem Beispielworkflow wird ein PostgreSQL-Dienstcontainer konfiguriert und Port 5432 im Dienstcontainer automatisch einem zufällig ausgewählten verfügbaren Port auf dem Host zugeordnet. Mit dem job-Kontext wird auf die Nummer des Ports zugegriffen, der dem Host zugewiesen wurde.

name: PostgreSQL Service Example
on: push
jobs:
  postgres-job:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          # Maps TCP port 5432 in the service container to a randomly chosen available port on the host.
          - 5432

    steps:
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: echo "Run tests against Postgres"

name: PostgreSQL Service Example
on: push
jobs:
  postgres-job:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
        ports:
          # Maps TCP port 5432 in the service container to a randomly chosen available port on the host.
          - 5432

    steps:
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: echo "Run tests against Postgres"

Kontext jobs

Der Kontext jobs ist nur in wiederverwendbaren Workflows verfügbar und kann nur verwendet werden, um Ausgaben für einen wiederverwendbaren Workflow festzulegen. Weitere Informationen finden Sie unter Wiederverwenden von Workflows.

Beispielinhalt des jobs-Kontexts

Dieses Beispiel für den Kontext jobs enthält das Ergebnis und die Ausgaben eines Auftrags aus einer wiederverwendbaren Workflowausführung.

{
  "example_job": {
    "result": "success",
    "outputs": {
      "output1": "hello",
      "output2": "world"
    }
  }
}

Beispielverwendung des jobs-Kontexts

In diesem Beispiel für einen wiederverwendbaren Workflow wird der jobs-Kontext verwendet, um Ausgaben für den wiederverwendbaren Workflow festzulegen. Beachte, wie die Ausgaben von den Schritten zum Auftrag und dann zum Trigger workflow_call fließen. Weitere Informationen finden Sie unter Wiederverwenden von Workflows.

name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

Kontext steps

Der steps-Kontext enthält Informationen zu den Schritten im aktuellen Auftrag, die über einen angegebenen id-Wert verfügen und bereits ausgeführt wurden.

Beispielinhalt des steps-Kontexts

In diesem steps-Beispielkontext siehst du zwei zuvor ausgeführte Schritte mit angegebenem id-Wert. Der id-Wert des ersten Schritts lautete checkout, der des zweiten Schritts generate_number. Die Ausgabe des Schritts generate_number lautete random_number.

{
  "checkout": {
    "outputs": {},
    "outcome": "success",
    "conclusion": "success"
  },
  "generate_number": {
    "outputs": {
      "random_number": "1"
    },
    "outcome": "success",
    "conclusion": "success"
  }
}

Beispielverwendung des steps-Kontexts

In diesem Beispielworkflow wird als Ausgabe in einem Schritt eine Zufallszahl generiert, deren Wert in einem späteren Schritt mit dem steps-Kontext gelesen wird.

name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - name: Generate 0 or 1
        id: generate_number
        run: echo "random_number=$(($RANDOM % 2))" >> $GITHUB_OUTPUT
      - name: Pass or fail
        run: |
          if [[ ${{ steps.generate_number.outputs.random_number }} == 0 ]]; then exit 0; else exit 1; fi

name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - name: Generate 0 or 1
        id: generate_number
        run: echo "random_number=$(($RANDOM % 2))" >> $GITHUB_OUTPUT
      - name: Pass or fail
        run: |
          if [[ ${{ steps.generate_number.outputs.random_number }} == 0 ]]; then exit 0; else exit 1; fi

Kontext runner

Der runner-Kontext enthält Informationen zum Runner, der den aktuellen Auftrag ausführt.

Beispielinhalt des runner-Kontexts

Der folgende Beispielkontext stammt von einem unter Linux gehosteten GitHub-Runner.

{
  "os": "Linux",
  "arch": "X64",
  "name": "GitHub Actions 2",
  "tool_cache": "/opt/hostedtoolcache",
  "temp": "/home/runner/work/_temp"
}

Beispielverwendung des runner-Kontexts

In diesem Beispielworkflow wird mit dem runner-Kontext der Pfad zum temporären Verzeichnis zum Schreiben von Protokollen festgelegt. Bei einem Fehler in der Workflowausführung werden diese Protokolle als Artefakt hochgeladen.

name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build with logs
        run: |
          mkdir ${{ runner.temp }}/build_logs
          echo "Logs from building" > ${{ runner.temp }}/build_logs/build.logs
          exit 1
      - name: Upload logs on fail
        if: ${{ failure() }}
        uses: actions/upload-artifact@v3
        with:
          name: Build failure logs
          path: ${{ runner.temp }}/build_logs

name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build with logs
        run: |
          mkdir ${{ runner.temp }}/build_logs
          echo "Logs from building" > ${{ runner.temp }}/build_logs/build.logs
          exit 1
      - name: Upload logs on fail
        if: ${{ failure() }}
        uses: actions/upload-artifact@v3
        with:
          name: Build failure logs
          path: ${{ runner.temp }}/build_logs

Kontext secrets

Der secrets-Kontext enthält die Namen und Werte von Geheimnissen, die für eine Workflowausführung verfügbar sind. Der secrets-Kontext ist aus Sicherheitsgründen nicht für zusammengesetzte Aktionen verfügbar. Wenn du ein Geheimnis an eine zusammengesetzte Aktion übergeben möchtest, musst du es explizit als Eingabe übergeben. Weitere Informationen zu Geheimnissen finden Sie unter Verwenden von Geheimnissen in GitHub-Aktionen.

Das Geheimnis GITHUB_TOKEN wird automatisch für jede Workflowausführung erstellt und ist in jedem secrets-Kontext enthalten. Weitere Informationen finden Sie unter Automatische Tokenauthentifizierung.

Beispielinhalt des secrets-Kontexts

Im folgenden Beispielinhalt des secrets-Kontexts siehst du das automatisch generierte Geheimnis GITHUB_TOKEN sowie zwei weitere Geheimnisse, die für die Workflowausführung verfügbar sind.

{
  "github_token": "***",
  "NPM_TOKEN": "***",
  "SUPERSECRET": "***"
}

Beispielverwendung des secrets-Kontexts

In diesem Beispielworkflow wird die GitHub CLI verwendet, die das GITHUB_TOKEN als Wert für den GH_TOKEN-Eingabeparameter erfordert:

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Kontext strategy

Für Workflows mit einer Matrix enthält der strategy-Kontext Informationen zur Ausführungsstrategie der Matrix für den aktuellen Auftrag.

Beispielinhalt des strategy-Kontexts

Der folgende Beispielinhalt des strategy-Kontexts stammt aus dem letzten Auftrag einer Matrix mit vier Aufträgen. Wie du siehst, unterscheidet sich die nullbasierte Anzahl für job-index von der nicht nullbasierten Anzahl für job-total.

{
  "fail-fast": true,
  "job-index": 3,
  "job-total": 4,
  "max-parallel": 4
}

Beispielverwendung des strategy-Kontexts

In diesem Beispielworkflow wird mit der Eigenschaft strategy.job-index ein eindeutiger Name für eine Protokolldatei für jeden Auftrag in einer Matrix festgelegt.

name: Test strategy
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [1, 2]
        node: [14, 16]
    steps:
      - run: echo "Mock test logs" > test-job-${{ strategy.job-index }}.txt
      - name: Upload logs
        uses: actions/upload-artifact@v3
        with:
          name: Build log for job ${{ strategy.job-index }}
          path: test-job-${{ strategy.job-index }}.txt

name: Test strategy
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [1, 2]
        node: [14, 16]
    steps:
      - run: echo "Mock test logs" > test-job-${{ strategy.job-index }}.txt
      - name: Upload logs
        uses: actions/upload-artifact@v3
        with:
          name: Build log for job ${{ strategy.job-index }}
          path: test-job-${{ strategy.job-index }}.txt

Kontext matrix

Für Workflows mit einer Matrix enthält der matrix-Kontext die Matrixeigenschaften, die in der Workflowdatei für den aktuellen Auftrag definiert sind. Wenn du z. B. eine Matrix mit den Schlüsseln os und node konfigurierst, enthält das matrix-Kontextobjekt die Eigenschaften os und node mit den Werten, die für den aktuellen Auftrag verwendet werden.

Der matrix-Kontext enthält nur die in der Workflowdatei definierten Eigenschaften, keine Standardeigenschaften.

Beispielinhalt des matrix-Kontexts

Der folgende Beispielinhalt des matrix-Kontexts stammt aus einem Auftrag in einer Matrix, die die im Workflow definierten Matrixeigenschaften os und node aufweist. Der Auftrag führt die Matrixkombination aus einem ubuntu-latest-Betriebssystem und Version 16 von Node.js aus.

{
  "os": "ubuntu-latest",
  "node": 16
}

Beispielverwendung des matrix-Kontexts

In diesem Beispielworkflow wird eine Matrix mit den Schlüsseln os und node erstellt. Mit der Eigenschaft matrix.os wird der Runnertyp und mit der Eigenschaft matrix.node die Version von Node.js für jeden Auftrag festgelegt.

name: Test matrix
on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - name: Output node version
        run: node --version

name: Test matrix
on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - name: Output node version
        run: node --version

Kontext needs

Der needs-Kontext enthält Ausgaben aller Aufträge, die als direkte Abhängigkeit des aktuellen Auftrags definiert sind. Beachte, dass das nicht für implizit abhängige Aufträge gilt (z. B. abhängige Aufträge eines abhängigen Auftrags). Weitere Informationen zum Definieren von Auftragsabhängigkeiten finden Sie unter Workflowsyntax für GitHub Actions.

Beispielinhalt des needs-Kontexts

Im folgenden Beispielinhalt des needs-Kontexts siehst du Informationen für zwei Aufträge, von denen der aktuelle Auftrag abhängt.

{
  "build": {
    "result": "success",
    "outputs": {
      "build_id": "123456"
    }
  },
  "deploy": {
    "result": "failure",
    "outputs": {}
  }
}

Beispielverwendung des needs-Kontexts

Dieser Beispielworkflow verfügt über drei Aufträge: einen build-Auftrag, der einen Build ausführt, einen deploy-Auftrag, für den der build-Auftrag benötigt wird, und einen debug-Auftrag, für den die Aufträge build und deploy benötigt werden und der nur bei einem Fehler im Workflow ausgeführt wird. Der deploy-Auftrag verwendet den needs-Kontext auch, um auf eine Ausgabe aus dem build-Auftrag zuzugreifen.

name: Build and deploy
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build_id: ${{ steps.build_step.outputs.build_id }}
    steps:
      - name: Build
        id: build_step
        run: echo "build_id=$RANDOM" >> $GITHUB_OUTPUT
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying build ${{ needs.build.outputs.build_id }}"
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - run: echo "Failed to build and deploy"

name: Build and deploy
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build_id: ${{ steps.build_step.outputs.build_id }}
    steps:
      - name: Build
        id: build_step
        run: echo "build_id=$RANDOM" >> $GITHUB_OUTPUT
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying build ${{ needs.build.outputs.build_id }}"
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - run: echo "Failed to build and deploy"

Kontext inputs

Der Kontext inputs enthält Eingabeeigenschaften, die an eine Aktion, einen wiederverwendbaren Workflow oder einen manuell ausgelösten Workflow übergeben werden. Für wiederverwendbare Workflows werden die Eingabenamen und -typen in der Konfiguration des workflow_call-Ereignisses eines wiederverwendbaren Workflows definiert. Die Eingabewerte werden von jobs.<job_id>.with in einem externen Workflow übergeben, der den wiederverwendbaren Workflow aufruft. Für manuell ausgelöste Workflows werden die Eingaben in der Konfiguration des workflow_dispatch-Ereignisses eines Workflows definiert.

Die Eigenschaften im inputs-Kontext werden in der Workflowdatei definiert. Sie sind nur in einem wiederverwendbaren Workflowoder in einem durch das Ereignis workflow_dispatch ausgelösten Workflow verfügbar.

Beispielinhalt des inputs-Kontexts

Der folgende Beispielinhalt des inputs-Kontexts stammt aus einem Workflow, der die Eingaben build_id, deploy_target und perform_deploy definiert hat.

{
  "build_id": 123456768,
  "deploy_target": "deployment_sys_1a",
  "perform_deploy": true
}

Beispielnutzung des inputs-Kontexts in einem wiederverwendbaren Workflow

In diesem Beispiel eines wiederverwendbaren Workflows werden mit dem inputs-Kontext die Werte der Eingaben build_id, deploy_target und perform_deploy abgerufen, die an den wiederverwendbaren Workflow vom aufrufenden Workflow übergeben wurden.

name: Reusable deploy workflow
on:
  workflow_call:
    inputs:
      build_id:
        required: true
        type: number
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}"

name: Reusable deploy workflow
on:
  workflow_call:
    inputs:
      build_id:
        required: true
        type: number
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}"

Beispielnutzung des inputs-Kontexts in einem manuell ausgelösten Workflow

In diesem Beispiel eines durch ein workflow_dispatch-Ereignis ausgelösten Workflows werden mit dem inputs-Kontext die Werte der Eingaben build_id, deploy_target und perform_deploy abgerufen, die an den Workflow übergeben wurden.

on:
  workflow_dispatch:
    inputs:
      build_id:
        required: true
        type: string
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}"

on:
  workflow_dispatch:
    inputs:
      build_id:
        required: true
        type: string
      deploy_target:
        required: true
        type: string
      perform_deploy:
        required: true
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ inputs.perform_deploy }}
    steps:
      - name: Deploy build to target
        run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}"