Skip to main content

Kontexte

Du kannst auf Kontextinformationen in Workflows und Aktionen zugreifen.

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 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 kannst du auf Kontexte zugreifen. Weitere Informationen findest du unter Ausdrücke.

${{ <context> }}

Warnung: Beim Erstellen von Workflows und Aktionen solltest du immer überprüfen, ob dein Code gegebenenfalls nicht vertrauenswürdige Eingaben von Angreifern ausführen kann. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen findest du unter „Grundlegendes zum Risiko von Skript-Einfügungen".

KontextnametypeBESCHREIBUNG
githubobjectInformationen zum Workflow-Lauf. Weitere Informationen findest du unter Kontext github.
envobjectEnthält Variablen, die in einem Workflow, Auftrag oder Schritt festgelegt sind. Weitere Informationen findest du unter Kontext env.

Als Teil eines Ausdrucks kannst du 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 du versuchst, 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 findest du unter Standardumgebungsvariablen.
  • 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 du bestimmte Kontexte innerhalb eines Workflows verwenden kannst, findest du 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"

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.

In der folgenden Tabelle siehst du, an welchen Stellen die einzelnen Kontexte und Sonderfunktionen innerhalb eines Workflows verwendet werden können. Funktionen, die nicht in der Liste aufgeführt werden, können überall verwendet werden.

| Workflowschlüssel | Kontext | Sonderfunktionen | | ---- | ------- | ----------------- | | concurrency | github, inputs | | | env | github, secrets, inputs | | | jobs.<job_id>.concurrency | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.container | github, needs, strategy, matrix, env, secrets, inputs | | | jobs.<job_id>.container.credentials | github, needs, strategy, matrix, env, secrets, inputs | | | jobs.<job_id>.container.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets, inputs | | | jobs.<job_id>.continue-on-error | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.defaults.run | github, needs, strategy, matrix, env, inputs | | | jobs.<job_id>.env | github, needs, strategy, matrix, secrets, inputs | | | jobs.<job_id>.environment | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.environment.url | github, needs, strategy, matrix, job, runner, env, steps, inputs | | | jobs.<job_id>.if | github, needs, inputs | always, cancelled, success, failure | | jobs.<job_id>.name | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.outputs.<output_id> | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | | | jobs.<job_id>.runs-on | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.secrets.<secrets_id> | github, needs, secrets | | | jobs.<job_id>.services | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.services.<service_id>.credentials | github, needs, strategy, matrix, env, secrets, inputs | | | jobs.<job_id>.services.<service_id>.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets, inputs | | | jobs.<job_id>.steps.continue-on-error | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.env | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.if | github, needs, strategy, matrix, job, runner, env, steps, inputs | always, cancelled, success, failure, hashFiles | | jobs.<job_id>.steps.name | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.run | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.timeout-minutes | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.with | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.steps.working-directory | github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs | hashFiles | | jobs.<job_id>.strategy | github, needs, inputs | | | jobs.<job_id>.timeout-minutes | github, needs, strategy, matrix, inputs | | | jobs.<job_id>.with.<with_id> | github, needs | | | on.workflow_call.inputs.<inputs_id>.default | github | | | on.workflow_call.outputs.<output_id>.value | github, jobs, inputs | |

Beispiel: Drucken von Kontextinformationen ins Protokoll

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

Warnung: Achte bei der Verwendung des gesamten github-Kontexts darauf, dass darin vertrauliche Informationen wie github.token enthalten sind. GitHub maskiert Geheimnisse, wenn sie auf die Konsole ausgegeben werden, aber du solltest beim Exportieren oder Drucken des Kontexts vorsichtig sein.

YAML
name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        id: github_context_step
        run: echo '${{ toJSON(github) }}'
      - name: Dump job context
        run: echo '${{ toJSON(job) }}'
      - name: Dump steps context
        run: echo '${{ toJSON(steps) }}'
      - name: Dump runner context
        run: echo '${{ toJSON(runner) }}'
      - name: Dump strategy context
        run: echo '${{ toJSON(strategy) }}'
      - name: Dump matrix context
        run: echo '${{ toJSON(matrix) }}'

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 kannst du auch in Umgebungsvariablen lesen. Weitere Informationen zu Umgebungsvariablen findest du unter Verwenden von Umgebungsvariablen.

Warnung: Achte bei der Verwendung des gesamten github-Kontexts darauf, dass darin vertrauliche Informationen wie github.token enthalten sind. GitHub maskiert Geheimnisse, wenn sie auf die Konsole ausgegeben werden, aber du solltest beim Exportieren oder Drucken des Kontexts vorsichtig sein.

Warnung: Beim Erstellen von Workflows und Aktionen solltest du immer überprüfen, ob dein Code gegebenenfalls nicht vertrauenswürdige Eingaben von Angreifern ausführen kann. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen findest du unter „Grundlegendes zum Risiko von Skript-Einfügungen".

EigenschaftennametypeBESCHREIBUNG
githubobjectDer Top-Level-Kontext, der bei jedem Job oder Schritt im Workflow verfügbar ist. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
github.actionstringName der aktuell ausgeführten Aktion oder der id-Wert eines Schritts. GitHub entfernt Sonderzeichen und verwendet den Namen __run, wenn der aktuelle Schritt ein Skript ohne id ausführt. Wenn du eine Aktion mehr als einmal im selben Auftrag verwendest, enthält der Name ein Suffix mit der Sequenznummer, der ein Unterstrich vorangestellt wird. So lautet z. B. der Name des ersten Skripts, das du ausführst, __run und der des zweiten __run_2. Analog dazu erhält der zweite Aufruf von actions/checkout den Namen actionscheckout2.
github.action_pathstringPfad einer Aktion. Diese Eigenschaft wird nur in zusammengesetzten Aktionen unterstützt. Mit diesem Pfad kannst du auf Dateien zugreifen, die sich im gleichen Repository wie die Aktion befinden.
github.action_refstringBei einem Schritt, in dem eine Aktion ausgeführt wird, verweist diese Eigenschaft auf die ausgeführte Aktion. Beispiel: v2.
github.action_repositorystringBei einem Schritt, in dem eine Aktion ausgeführt wird, gibt diese Eigenschaft den Namen des Besitzers bzw. der Besitzerin und des Repositorys der Aktion an. Beispiel: actions/checkout.
github.action_statusstringDas aktuelle Ergebnis einer zusammengesetzten Aktion.
github.actorstringDer Benutzername des Benutzers bzw. der Benutzerin, der/die die Workflowausführung initiiert hat.
github.api_urlstringURL der GitHub-REST-API.
github.base_refstringbase_ref- oder Zielbranch des Pull Requests in einer Workflowausführung. Diese Eigenschaft ist nur verfügbar, wenn es sich bei dem Ereignis, das eine Workflowausführung auslöst, um pull_request oder pull_request_target handelt.
github.envstringPfad des Runners zur Datei, die Umgebungsvariablen aus Workflowbefehlen festlegt. Diese Datei ist für den aktuellen Schritt eindeutig und unterscheidet sich für jeden Schritt in einem Auftrag. Weitere Informationen findest du unter Workflowbefehle für GitHub Actions.
github.eventobjectDie vollständige Nutzlast des Ereignis-Webhooks. Mit diesem Kontext kannst du auf einzelne Eigenschaften des Ereignisses zugreifen. Dieses Objekt ist identisch mit der Webhooknutzlast des Ereignisses, das die Workflowausführung ausgelöst hat, und unterscheidet sich für jedes Ereignis. Die Webhooks für jedes GitHub Actions-Ereignis werden unter Ereignisse, die Workflows auslösen verknüpft. Für einen Workflow, der vom Ereignis push ausgelöst wird, enthält dieses Objekt beispielsweise den Inhalt der Webhooknutzlast „push“.
github.event_namestringDer Name des Ereignisses, das den Workflow-Lauf ausgelöst hat.
github.event_pathstringPfad des Runners zur Datei mit der vollständigen Webhooknutzlast des Ereignisses.
github.graphql_urlstringURL der GitHub-GraphQL-API.
github.head_refstringhead_ref- oder Quellbranch des Pull Requests in einer Workflowausführung. Diese Eigenschaft ist nur verfügbar, wenn es sich bei dem Ereignis, das eine Workflowausführung auslöst, um pull_request oder pull_request_target handelt.
github.jobstringjob_id-Wert des aktuellen Auftrags.
Hinweis: Diese Kontexteigenschaft wird vom Actions-Runner festgelegt und ist nur innerhalb der steps der Ausführung eines Auftrags verfügbar. Andernfalls ist der Wert dieser Eigenschaft null.
github.refstringDas vollständig geformte Ref des Branch- oder Tagnamens, der die Workflowausführung ausgelöst hat. Bei Workflows, die durch push ausgelöst wurden, ist dies das Branch- oder Tag-Ref, das gepusht wurde. Bei Workflows, die von pull_request ausgelöst werden, ist dies der Branch für das Mergen des Pull Requests. Bei Workflows, die von release ausgelöst werden, ist dies das erstellte Releasetag. Bei anderen Triggern handelt es sich um das Branch- oder Tag-Ref, das die Workflowausführung ausgelöst hat. Es wird nur festgelegt, wenn für den Ereignistyp ein Branch oder ein Tag verfügbar ist. Das Ref ist vollständig gebildet, d.h. für Branches ist das Format refs/heads/<branch_name>, für Pull Requests refs/pull/<pr_number>/merge und für Tags refs/tags/<tag_name>. Beispiel: refs/heads/feature-branch-1.

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.

Hinweis: Dieser Kontext ist nur ein Beispiel. Der Inhalt eines Kontexts hängt vom ausgeführten Workflow ab. Kontexte, Objekte und Eigenschaften variieren bei verschiedenen Workflowausführungsbedingungen erheblich.

{
  "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.

YAML
name: Run CI
on: [push, pull_request]

jobs:
  normal_ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run normal CI
        run: ./run-tests

  pull_request_ci:
    runs-on: ubuntu-latest
    if: ${{ github.event_name == 'pull_request' }}
    steps:
      - uses: actions/checkout@v3
      - name: Run PR CI
        run: ./run-additional-pr-ci

Kontext env

Der env-Kontext enthält Variablen, die in einem Workflow, Auftrag oder Schritt festgelegt wurden. Weitere Informationen zum Festlegen von Variablen in deinem Workflow findest du unter Workflowsyntax für GitHub Actions.

Mit der Syntax für den env-Kontext kannst du den Wert einer Variablen in der Workflowdatei verwenden. Du kannst 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 findest du unter Workflowsyntax für GitHub Actions.

Wenn du den Wert einer Variablen innerhalb eines Runners verwenden willst, dann verwende die übliche Methode des Runnerbetriebssystems zum Lesen von Umgebungsvariablen.

EigenschaftennametypeBESCHREIBUNG
envobjectDieser Kontext ändert sich bei jedem Schritt in einem Auftrag. Du kannst bei jedem Schritt in einem Auftrag auf diesen Kontext zugreifen. Dieses Objekt enthält die unten aufgeführten Eigenschaften.
env.<env_name>stringDer Wert einer bestimmten Umgebungsvariable.

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.

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

Beispielverwendung des env-Kontexts

In diesem Beispielworkflow wird gezeigt, wie du den env-Kontext auf der Workflow-, Auftrags- und Schrittebene konfigurierst sowie den Kontext in Schritten verwendest.

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.

YAML
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 job

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

EigenschaftennametypeBESCHREIBUNG
jobobjectDieser Kontext ändert sich bei jedem Auftrag in einem Workflow-Lauf. Du kannst bei jedem Schritt in einem Auftrag auf diesen Kontext zugreifen. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
job.containerobjectInformationen zum Container des Auftrags. Weitere Informationen zu Containern findest du unter Workflowsyntax für GitHub Actions.
job.container.idstringID des Containers.
job.container.networkstringID des Containernetzwerks. Der Runner erstellt das Netzwerk, das von allen Containern in einem Auftrag genutzt wird.
job.servicesobjectDie für einen Auftrag erstellten Dienstcontainer. Weitere Informationen zu Dienstcontainern findest du unter Workflowsyntax für GitHub Actions.
job.services.<service_id>.idstringID des Dienstcontainers.
job.services.<service_id>.networkstringID des Dienstcontainernetzwerks. Der Runner erstellt das Netzwerk, das von allen Containern in einem Auftrag genutzt wird.
job.services.<service_id>.portsobjectDie offengelegten Ports des Service-Containers
job.statusstringDen aktuellen Status des Auftrags. Mögliche Werte sind success, failure oder cancelled.

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.

YAML
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:
      - uses: actions/checkout@v3
      - run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
      - run: ./run-tests

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 findest du unter Wiederverwenden von Workflows.

EigenschaftennametypeBESCHREIBUNG
jobsobjectIst ausschließlich in wiederverwendbaren Workflows verfügbar und kann nur verwendet werden, um Ausgaben für einen wiederverwendbaren Workflow festzulegen. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
jobs.<job_id>.resultstringDas Ergebnis eines Auftrags im wiederverwendbaren Workflow. Mögliche Werte sind success, failure, cancelled oder skipped.
jobs.<job_id>.outputsobjectDer Ausgabensatz eines Auftrags in einem wiederverwendbaren Workflow.
jobs.<job_id>.outputs.<output_name>stringDer Wert einer spezifischen Ausgabe für einen Auftrag in einem wiederverwendbaren Workflow.

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 findest du unter Wiederverwenden von Workflows.

YAML
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 "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

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.

EigenschaftennametypeBESCHREIBUNG
stepsobjectDieser Kontext ändert sich bei jedem Schritt in einem Auftrag. Du kannst bei jedem Schritt in einem Auftrag auf diesen Kontext zugreifen. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
steps.<step_id>.outputsobjectDer Satz an Ausgaben, die für diesen Schritt definiert wurden. Weitere Informationen findest du unter Metadatensyntax für GitHub Actions.
steps.<step_id>.conclusionstringErgebnis eines abgeschlossenen Schritts nach der Anwendung von continue-on-error. Mögliche Werte sind success, failure, cancelled oder skipped. Tritt bei einem Schritt vom Typ continue-on-error ein Fehler auf, lautet der outcome-Wert failure, doch der endgültige conclusion-Wert lautet success.
steps.<step_id>.outcomestringErgebnis eines abgeschlossenen Schritts vor der Anwendung von continue-on-error. Mögliche Werte sind success, failure, cancelled oder skipped. Tritt bei einem Schritt vom Typ continue-on-error ein Fehler auf, lautet der outcome-Wert failure, doch der endgültige conclusion-Wert lautet success.
steps.<step_id>.outputs.<output_name>stringDer Wert einer bestimmten Ausgabe

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.

YAML
name: Generate random failure
on: push
jobs:
  randomly-failing-job:
    runs-on: ubuntu-latest
    steps:
      - id: checkout
        uses: actions/checkout@v3
      - name: Generate 0 or 1
        id: generate_number
        run:  echo "::set-output name=random_number::$(($RANDOM % 2))"
      - 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.

EigenschaftennametypeBESCHREIBUNG
runnerobjectDieser Kontext ändert sich bei jedem Auftrag in einem Workflow-Lauf. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
runner.namestringDer Name des Runners, der den Auftrag ausführt.
runner.osstringDas Betriebssystem des Runners, der den Job ausführt. Mögliche Werte sind Linux, Windows oder macOS.
runner.archstringDie Architektur des Runners, der den Auftrag ausführt. Mögliche Werte sind X86, X64, ARM oder ARM64.
runner.tempstringDer Pfad zu einem temporären Verzeichnis im Runner. Dieses Verzeichnis wird jeweils zu Beginn und am Ende eines Auftrags geleert. Hinweis: Wenn das Benutzerkonto des Runners über keine Berechtigung zum Löschen verfügt, werden keine Dateien entfernt.
runner.tool_cachestringDer Pfad zu dem Verzeichnis, das vorinstallierte Tools für von GitHub gehostete Runner enthält. Weitere Informationen findest du unter Informationen zu von GitHub gehosteten Runnern.
runner.debugstringDies ist nur festgelegt, wenn die Debugprotokollierung aktiviert ist, und weist immer den Wert 1 auf. Es kann ein nützlicher Hinweis darauf sein, ob in deinen Auftragsschritten zusätzliches Debugging oder eine ausführliche Protokollierung aktiviert werden sollte.

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.

YAML
name: Build
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build with logs
        run: |
          mkdir ${{ runner.temp }}/build_logs
          ./build.sh --log-path ${{ runner.temp }}/build_logs
      - 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 findest du unter Verschlüsselte Geheimnisse.

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

Warnung: GitHub redigiert automatisch Geheimnisse, die im Protokoll erfasst wurden. Du solltest Geheimnisse jedoch nicht absichtlich im Protokoll erfassen lassen.

EigenschaftennametypeBESCHREIBUNG
secretsobjectDieser Kontext ist für jeden Auftrag in einer Workflowausführung identisch. Du kannst bei jedem Schritt in einem Auftrag auf diesen Kontext zugreifen. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
secrets.GITHUB_TOKENstringAutomatisch erstelltes Token für jede Workflowausführung. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.
secrets.<secret_name>stringWert eines bestimmten Geheimnisses.

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 Beschrifteraktion verwendet, die das GITHUB_TOKEN als Wert für den repo-token-Eingabeparameter erfordert:

YAML
name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-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.

EigenschaftennametypeBESCHREIBUNG
strategyobjectDieser Kontext ändert sich bei jedem Auftrag in einem Workflow-Lauf. Auf diesen Kontext kannst du von jedem Auftrag oder Schritt in einem Workflow zugreifen. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
strategy.fail-fastbooleanBei true werden alle ausgeführten Aufträge abgebrochen, wenn bei einem Auftrag in einer Matrix ein Fehler auftritt. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.
strategy.job-indexnumberIndex des aktuellen Auftrags in der Matrix. Hinweis: Diese Zahl ist nullbasiert. Der Index des ersten Auftrags in der Matrix ist 0.
strategy.job-totalnumberDie Gesamtanzahl der Aufträge in der Matrix. Hinweis: Diese Zahl ist nicht nullbasiert. Für eine Matrix mit vier Aufträgen ist der Wert von job-total z. B. 4.
strategy.max-parallelnumberMaximale Anzahl der Aufträge, die bei Verwendung einer matrix-Auftragsstrategie gleichzeitig ausgeführt werden können. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

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.

YAML
name: Test matrix
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [1, 2]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v3
      - run: npm test > 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.

EigenschaftennametypeBESCHREIBUNG
matrixobjectDieser Kontext ist nur für Aufträge in einer Matrix verfügbar und unterscheidet sich für jeden Auftrag in einer Workflowausführung. Auf diesen Kontext kannst du von jedem Auftrag oder Schritt in einem Workflow zugreifen. Dieses Objekt enthält die unten aufgeführten Eigenschaften.
matrix.<property_name>stringWert einer Matrixeigenschaft.

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.

YAML
name: Test matrix
on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [14, 16]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

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 findest du unter Workflowsyntax für GitHub Actions.

EigenschaftennametypeBESCHREIBUNG
needsobjectDieser Kontext wird nur für Workflowausführungen mit abhängigen Aufträgen ausgefüllt und unterscheidet sich für jeden Auftrag in einer Workflowausführung. Auf diesen Kontext kannst du von jedem Auftrag oder Schritt in einem Workflow zugreifen. Dieses Objekt enthält alle unten aufgeführten Eigenschaften.
needs.<job_id>objectEin einzelner Job, von dem der aktuelle Job abhängt.
needs.<job_id>.outputsobjectDie Menge aller Ausgaben eines Jobs, von dem der aktuelle Job abhängt.
needs.<job_id>.outputs.<output name>stringDer Wert einer bestimmten Ausgabe für einen Job, von dem der aktuelle Job abhängt.
needs.<job_id>.resultstringDas Ergebnis eines Jobs, von dem der aktuelle Job abhängt. Mögliche Werte sind success, failure, cancelled oder skipped.

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": "ABC123"
    }
  },
  "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.

YAML
name: Build and deploy
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build_id: ${{ steps.build_step.outputs.build_id }}
    steps:
      - uses: actions/checkout@v3
      - name: Build
        id: build_step
        run: |
          ./build
          echo "::set-output name=build_id::$BUILD_ID"
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: ./deploy --build ${{ needs.build.outputs.build_id }}
  debug:
    needs: [build, deploy]
    runs-on: ubuntu-latest
    if: ${{ failure() }}
    steps:
      - uses: actions/checkout@v3
      - run: ./debug

Kontext inputs

Der inputs-Kontext enthält Eingabeeigenschaften, die an eine Aktion oder einen wiederverwendbaren Workflow. für wiederverwendbare Workflows werden 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.

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

EigenschaftennametypeBESCHREIBUNG
inputsobjectDieser Kontext ist nur in einem wiederverwendbaren Workflow. Auf diesen Kontext kannst du von jedem Auftrag oder Schritt in einem Workflow zugreifen. Dieses Objekt enthält die unten aufgeführten Eigenschaften.
inputs.<name>string oder number oder booleanJeder Eingabewert, der von einem externen Workflow übergeben wurde.

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.

YAML
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: deploy --build ${{ inputs.build_id }} --target ${{ inputs.deploy_target }}