Wiederverwenden von Workflows

Übersicht

Damit du nicht zwischen Workflows kopieren musst, kannst du Workflows wiederverwendbar machen. Du und alle anderen, die Zugriff auf den wiederverwendbaren Workflow haben, können diesen dann in einem anderen Workflow aufrufen.

Durch das Wiederverwenden von Workflows wird Duplizierung vermieden. Dies vereinfacht die Wartung von Workflows und ermöglicht ein schnelleres Erstellen neuer Workflows, da auf der Arbeit anderer aufgebaut werden kann, genau wie bei Aktionen. Die Wiederverwendung von Workflows fördert auch die Nutzung bewährter Methoden, da sie dich dabei unterstützt, gut strukturierte Workflows zu verwenden, die bereits getestet wurden und sich als effektiv erwiesen haben. Deine Organisation kann eine Bibliothek mit wiederverwendbaren Workflows erstellen, die zentral verwaltet werden kann.

Das folgende Diagramm zeigt eine laufende Workflowausführung, die einen wiederverwendbaren Workflow verwendet.

• Nachdem jeder der drei Buildaufträge auf der linken Seite des Diagramms erfolgreich abgeschlossen wurde, wird ein abhängiger Auftrag namens „Deploy“ ausgeführt.
• Im „Deploy“-Auftrag wird ein wiederverwendbarer Workflow aufgerufen, der drei Aufträge enthält: „Staging“, „Review“ und „Production“.
• Der Bereitstellungsauftrag „Production“ wird erst ausgeführt, wenn der Auftrag „Staging“ erfolgreich abgeschlossen wurde.
• Wenn ein Auftrag auf eine Umgebung abzielt, zeigt die Workflowausführung eine Statusleiste an, die die Anzahl der Schritte im Auftrag anzeigt. Im folgenden Diagramm enthält der Auftrag „Production“ acht Schritte, wobei Schritt 6 derzeit verarbeitet wird.
• Die Nutzung eines wiederverwendbaren Workflows für das Ausführen von Bereitstellungsaufträgen ermöglicht dir das Ausführen dieser Aufträge für jeden Build, ohne dass du Code in Workflows duplizieren musst.

Ein Workflow, in dem ein anderer Workflow verwendet wird, wird als aufrufender Workflow bezeichnet. Der wiederverwendbare Workflow ist ein aufgerufener Workflow. In einem aufrufenden Workflow können mehrere aufgerufene Workflows verwendet werden. Auf jeden aufgerufenen Workflow wird in nur jeweils einer Zeile verwiesen. Dies führt dazu, dass die Datei mit dem aufrufenden Workflow möglicherweise nur ein paar wenige Zeilen YAML-Code enthält, beim Ausführen jedoch viele Tasks ausführt. Wenn du einen Workflow wiederverwendest, wird der gesamte aufgerufene Workflow verwendet, als wäre er Teil des aufrufenden Workflows.

Wenn du einen Workflow aus einem anderen Repository wiederverwendest, werden alle Aktionen im aufgerufenen Workflow ausgeführt, als wären sie Teil des aufrufenden Workflows. Wenn im aufgerufenen Workflow actions/checkout verwendet wird, überprüft die Aktion beispielsweise den Inhalt des Repositorys, in dem der aufrufende Workflow gehostet wird, nicht den des Repositorys des aufgerufenen Workflows.

Wenn ein wiederverwendbarer Workflow durch einen aufrufenden Workflow ausgelöst wird, wird der Kontext github immer dem aufrufenden Workflow zugeordnet. Dem aufgerufenen Workflow wird automatisch Zugriff auf github.token und secrets.GITHUB_TOKEN gewährt. Weitere Informationen zum github-Kontext findest du unter Kontexte.

Du kannst die wiederverwendeten Workflows, auf die in deinen GitHub Actions-Workflows verwiesen wird, im Abhängigkeitsdiagramm des Repositorys, in dem deine Workflows sich befinden, als Abhängigkeiten anzeigen. Weitere Informationen findest du unter Informationen zum Abhängigkeitsdiagramm.

Wiederverwendbare Workflows und Starterworkflows

Mit Starterworkflows können alle Personen in deiner Organisation, die über die entsprechenden Berechtigungen verfügen, Workflows schneller und leichter erstellen. Wenn sie einen neuen Workflow erstellen, können sie einen Starterworkflow auswählen und sich so das Schreiben des Workflows ganz oder teilweise sparen. In einem Starterworkflow kann auch auf wiederverwendbare Workflows verwiesen werden, damit Benutzer*innen leicht von der Wiederverwendung zentral verwalteten Workflowcodes profitieren können. Wenn du beim Verweisen auf den wiederverwendbaren Workflow einen Commit-SHA verwendest, kannst du sicherstellen, dass Personen, die diesen Workflow wiederverwenden, immer denselben YAML-Code nutzen. Wenn du über ein Tag oder einen Branch auf einen wiederverwendbaren Workflow verweist, musst du jedoch sicherstellen, dass diese Version des Workflows vertrauenswürdig ist. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions.

Weitere Informationen findest du unter Erstellen von Startworkflows für deine Organisation.

Zugriff auf wiederverwendbare Workflows

Ein wiederverwendbarer Workflow kann von einem anderen Workflow verwendet werden, wenn einer der folgenden Punkte zutrifft:

• Beide Workflows befinden sich im selben Repository.
• Der aufgerufene Workflow befindet sich in einem öffentlichen Repository.
• Der aufgerufene Workflow befindet sich in einem internen Repository, und die Einstellungen für dieses Repository ermöglichen den Zugriff darauf. Weitere Informationen findest du unter Freigeben von Aktionen und Workflows in deinem Unternehmen.
• Der aufgerufene Workflow befindet sich in einem privaten Repository, und die Einstellungen für dieses Repository ermöglichen den Zugriff darauf. Weitere Informationen findest du unter Freigeben von Aktionen und Workflows in deinem Unternehmen.

Verwenden von Runnern

Verwenden von auf GitHub gehosteten Runnern

Die Zuweisung von auf GitHub gehosteten Runnern wird immer nur mit dem Kontext des aufrufenden Workflows ausgewertet. Die Abrechnung für auf GitHub gehostete Runner wird immer dem aufrufenden Workflow zugeordnet. Der aufrufende Workflow kann auf GitHub gehostete Runner nicht über das aufgerufene Repository verwenden. Weitere Informationen findest du unter Verwenden von auf GitHub gehosteten Runnern.

Verwenden von selbstgehosteten Runnern

Aufgerufene Workflows, die demselben Benutzer bzw. derselben Benutzerin oder derselben Organisation oder demselben Unternehmen gehören wie der aufrufende Workflow, können über den Kontext des aufrufenden Workflows auf selbstgehostete Runner zugreifen. Dies bedeutet, dass ein aufgerufener Workflow auf selbstgehostete Runner zugreifen kann, auf die Folgendes zutrifft:

• Du befindest dich im Repository des aufrufenden Workflows.
• Du gehörst zur selben Organisation oder zum selben Unternehmen wie das Repository des aufrufenden Workflows, und der Runner wurde für das aufrufende Repository verfügbar gemacht.

Begrenzungen

• Du kannst bis zu vier Workflowebenen verbinden. Weitere Informationen findest du unter Schachteln wiederverwendbarer Workflows.

• Sie können maximal 20 verschiedene wiederverwendbare Workflows aus einer einzelnen Workflowdatei aufrufen. Dieser Grenzwert gilt für alle Strukturen von geschachtelten wiederverwendbaren Workflows, die ab der Workflowdatei der aufrufenden Funktion der obersten Ebene aufgerufen werden können.

  Beispielsweise zählt top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml als zwei wiederverwendbare Workflows.

• Alle Umgebungsvariablen, die in einem env-Kontext festgelegt werden, der im aufrufenden Workflow auf Workflowebene definiert ist, werden nicht an den aufgerufenen Workflow übergeben. Weitere Informationen findest du unter Variablen und unter Kontexte.

• Auf ähnliche Weise sind im env-Kontext festgelegte Umgebungsvariablen, die im aufgerufenen Workflow definiert sind, im env-Kontext des Aufruferworkflows nicht zugänglich. Stattdessen musst du Ausgaben des wiederverwendbaren Workflows verwenden. Weitere Informationen sind unter „Verwenden von Ausgaben eines wiederverwendbaren Workflows“ zu finden.

• Um Variablen in mehreren Workflows wiederzuverwenden, lege sie auf Organisations-, Repository- oder Umgebungsebene fest, und verweise mithilfe des Kontexts vars darauf. Weitere Informationen findest du unter Variablen und unter Kontexte.

• Wiederverwendbare Workflows werden direkt innerhalb eines Auftrags aufgerufen und nicht innerhalb eines Auftragsschritts. Du kannst daher GITHUB_ENV verwenden, um Werte an die Auftragsschritte im Aufruferworkflow zu übergeben.

Erstellen eines wiederverwendbaren Workflows

Wiederverwendbare Workflows sind Dateien mit YAML-Code, die anderen Workflowdateien sehr ähneln. Wie andere Workflowdateien auch, findest du wiederverwendbare Workflows im Verzeichnis .github/workflows eines Repositorys. Unterverzeichnisse des Verzeichnisses workflows werden nicht unterstützt.

Damit ein Workflow wiederverwendbar ist, müssen die Werte für on workflow_call beinhalten:

on:
  workflow_call:

Verwenden von Eingaben und Geheimnissen in einem wiederverwendbaren Workflow

Du kannst Eingaben und Geheimnisse definieren, die vom aufrufenden Workflow übergeben und im aufgerufenen Workflow verwendet werden können. Für die Verwendung einer Eingabe oder eines Geheimnisses in einem wiederverwendbaren Workflow sind drei Schritte erforderlich.

1. Verwende im wiederverwendbaren Workflow die Schlüsselwörter inputs und secrets, um Eingaben oder Geheimnisse zu definieren, die von einem aufrufenden Workflow übergeben werden.

   on:
     workflow_call:
       inputs:
         config-path:
           required: true
           type: string
       secrets:
         envPAT:
           required: true
   

Ausführliche Informationen zur Syntax zum Definieren von Eingaben und Geheimnissen findest du unter on.workflow_call.inputs und on.workflow_call.secrets.

1. Verweise im wiederverwendbaren Workflow auf die Eingabe oder das Geheimnis, die bzw. das du im vorherigen Schritt im Schlüssel on definiert hast.

   Hinweis: Wenn die Geheimnisse durch Verwendung von secrets: inherit im aufrufenden Workflow geerbt werden, kannst du auch dann auf sie verweisen, wenn sie im on-Schlüssel nicht explizit definiert sind. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

   jobs:
     reusable_workflow_job:
       runs-on: ubuntu-latest
       environment: production
       steps:
       - uses: actions/labeler@v4
         with:
           repo-token: ${{ secrets.envPAT }}
           configuration-path: ${{ inputs.config-path }}
   

Im obigen Beispiel ist envPAT ein Umgebungsgeheimnis, das der Umgebung production hinzugefügt wurde. Daher wird im Auftrag auf diese Umgebung verwiesen.

1. Übergib die Eingabe oder das Geheimnis aus dem aufrufenden Workflow.

   Verwende das Schlüsselwort with in einem Auftrag, um benannte Eingaben an einen aufgerufenen Workflow zu übergeben. Verwende das Schlüsselwort secrets, um benannte Geheimnisse zu übergeben. Bei Eingaben muss der Datentyp des Eingabewerts dem Typ entsprechen, der im aufgerufenen Workflow angegeben ist (boolescher Wert, Zahl oder Zeichenfolge).

   jobs:
     call-workflow-passing-data:
       uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
       with:
         config-path: .github/labeler.yml
       secrets:
         envPAT: ${{ secrets.envPAT }}
   

   Workflows, die wiederverwendbare Workflows in derselben Organisation oder im selben Unternehmen aufrufen, können das Schlüsselwort inherit verwenden, um die Geheimnisse implizit zu übergeben.

   jobs:
     call-workflow-passing-data:
       uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
       with:
         config-path: .github/labeler.yml
       secrets: inherit
   

Beispiel für einen wiederverwendbaren Workflow

In dieser Datei namens workflow-B.yml mit einem wiederverwendbaren Workflow (wir verweisen später im Beispiel für einen aufrufenden Workflow darauf) werden eine Eingabezeichenfolge und ein Geheimnis aus dem aufrufenden Workflow abgerufen und in einer Aktion verwendet.

name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

Aufrufen eines wiederverwendbaren Workflows

Zum Aufrufen eines wiederverwendbaren Workflows wird das Schlüsselwort uses verwendet. Anders als bei der Verwendung von Aktionen in einem Workflow werden wiederverwendbare Workflows direkt in einem Auftrag aufgerufen und nicht in Auftragsschritten.

jobs.<job_id>.uses

Sie verweisen auf wiederverwendbare Workflowdateien mithilfe einer der folgenden Syntaxen:

• {owner}/{repo}/.github/workflows/{filename}@{ref} für wiederverwendbare Workflows in öffentlichen, internen und privaten Repositorys.
• ./.github/workflows/{filename} für wiederverwendbare Workflows im selben Repository.

Bei der ersten Option kann {ref} ein SHA, ein Releasetag oder ein Branchname sein. Wenn ein Releasetag und ein Branch denselben Namen aufweisen, hat das Releasetag Vorrang vor dem Branchnamen. Die Verwendung des Commit-SHA-Werts ist die beste Option im Hinblick auf Stabilität und Sicherheit. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions.

Wenn du die zweite Syntaxoption verwendest (ohne {owner}/{repo} und @{ref}), stammt der aufgerufene Workflow aus demselben Commit wie der aufrufende Workflow. Verweispräfixe wie refs/heads und refs/tags sind nicht zulässig.

Du kannst mehrere Workflows aufrufen, indem du jeweils in einem eigenen Auftrag auf diese verweist.

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

Übergeben von Eingaben und Geheimnissen an einen wiederverwendbaren Workflow

Verwende das Schlüsselwort with in einem Auftrag, um benannte Eingaben an einen aufgerufenen Workflow zu übergeben. Verwende das Schlüsselwort secrets, um benannte Geheimnisse zu übergeben. Bei Eingaben muss der Datentyp des Eingabewerts dem Typ entsprechen, der im aufgerufenen Workflow angegeben ist (boolescher Wert, Zahl oder Zeichenfolge).

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      envPAT: ${{ secrets.envPAT }}

Workflows, die wiederverwendbare Workflows in derselben Organisation oder im selben Unternehmen aufrufen, können das Schlüsselwort inherit verwenden, um die Geheimnisse implizit zu übergeben.

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

Verwenden einer Matrixstrategie mit einem wiederverwendbaren Workflow

Aufträge, die die Matrixstrategie verwenden, können einen wiederverwendbaren Workflow aufrufen.

Mithilfe einer Matrixstrategie kannst du Variablen in einer Auftragsdefinition verwenden, um automatisch mehrere Auftragsausführungen zu erstellen, die auf Kombinationen dieser Variablen basieren. Beispielsweise kannst du eine Matrixstrategie verwenden, um verschiedene Eingaben an einen wiederverwendbaren Workflow zu übergeben. Weitere Informationen zu Matrizen findest du unter Verwenden von Matrizen für deine Aufträge.

Der folgende Beispielauftrag ruft einen wiederverwendbaren Workflow auf und verweist auf den Matrixkontext, indem die Variable target mit den Werten [dev, stage, prod] definiert wird. Er führt drei Aufträge aus, einen für jeden Wert in der Variablen.

jobs:
  ReuseableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

jobs:
  ReuseableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

Unterstützte Schlüsselwörter für Aufträge, in denen ein wiederverwendbarer Workflow aufgerufen wird

Beim Aufrufen eines wiederverwendbaren Workflows kannst du in dem Auftrag, der den Aufruf enthält, nur die folgenden Schlüsselwörter verwenden:

• jobs.<job_id>.name

• jobs.<job_id>.uses

• jobs.<job_id>.with

• jobs.<job_id>.with.<input_id>

• jobs.<job_id>.secrets

• jobs.<job_id>.secrets.<secret_id>

• jobs.<job_id>.secrets.inherit

• jobs.<job_id>.strategy

• jobs.<job_id>.needs

• jobs.<job_id>.if

• jobs.<job_id>.concurrency

• jobs.<job_id>.permissions

  Hinweis:

  • Wenn im aufrufenden Auftrag jobs.<job_id>.permissions nicht angegeben ist, verfügt der aufgerufene Workflow über die Standardberechtigungen für GITHUB_TOKEN. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.
  • Die vom aufrufenden Workflow übergebenen GITHUB_TOKEN-Berechtigungen können im aufgerufenen Workflow nur eingeschränkt werden (und nicht erweitert).
  • Wenn Sie jobs.<job_id>.concurrency.cancel-in-progress: true verwenden, dürfen Sie für jobs.<job_id>.concurrency.group in den aufgerufenen und aufrufenden Workflows nicht gen gleichen Wert verwenden, da sonst der bereits ausgeführte Workflow abgebrochen wird. Ein aufgerufener Workflow verwendet den Namen des aufrufenden Workflows in ${{ github.workflow }}, sodass die Verwendung dieses Kontexts als Wert von jobs.<job_id>.concurrency.group im aufrufenden und aufgerufenen Workflow dazu führt, dass der aufrufende Workflow abgebrochen wird, wenn der aufgerufene Workflow ausgeführt wird.

Beispiel für einen aufrufenden Workflow

In dieser Workflowdatei werden zwei Workflowdateien aufgerufen. Der zweiten davon (workflow-B.yml, im Beispiel für einen wiederverwendbaren Workflow zu sehen) werden eine Eingabe (config-path) und ein Geheimnis (token) übergeben.

name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    permissions:
      contents: read
      pull-requests: write
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    permissions:
      contents: read
      pull-requests: write
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

Schachteln wiederverwendbarer Workflows

Du kannst maximal vier Workflowebenen verbinden – also den Workflow auf oberster Ebene und bis zu drei Ebenen wiederverwendbarer Workflows. Beispiel: caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml → called-workflow-3.yml. Schleifen in der Workflowstruktur sind nicht zulässig.

Aus einem wiederverwendbaren Workflow kannst du einen anderen wiederverwendbaren Workflow aufrufen.

name: Reusable workflow

on:
  workflow_call:

jobs:
  call-another-reusable:
    uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1

name: Reusable workflow

on:
  workflow_call:

jobs:
  call-another-reusable:
    uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1

Übergeben von Geheimnissen an geschachtelte Workflows

Du kannst jobs.<job_id>.secrets in einem aufrufenden Workflow verwenden, um benannte Geheimnisse an einen direkt aufgerufenen Workflow zu übergeben. Alternativ kannst du mit jobs.<job_id>.secrets.inherit alle Geheimnisse des aufrufenden Workflows an einen direkt aufgerufenen Workflow übergeben. Weitere Informationen findest du weiter oben im Abschnitt Wiederverwenden von Workflows oben und im Referenzartikel Workflowsyntax für GitHub Actions. Geheimnisse werden nur an einen direkt aufgerufenen Workflow übergeben. In der Workflowkette A > B > C erhält Workflow C nur dann Geheimnisse von A, wenn sie von A an B und dann von B an C übergeben werden.

Im folgenden Beispiel übergibt Workflow A über das Schlüsselwort inherit alle Geheimnisse an Workflow B. Workflow B übergibt jedoch nur ein Geheimnis an Workflow C. Alle übrigen Geheimnisse, die an Workflow B übergeben werden, sind für Workflow C nicht verfügbar.

jobs:
  workflowA-calls-workflowB:
    uses: octo-org/example-repo/.github/workflows/B.yml@main
    secrets: inherit # pass all secrets

jobs:
  workflowB-calls-workflowC:
    uses: different-org/example-repo/.github/workflows/C.yml@main
    secrets:
      envPAT: ${{ secrets.envPAT }} # pass just this secret

Zugriff und Berechtigungen

Ein Workflow, der geschachtelte wiederverwendbare Workflows enthält, schlägt fehl, wenn einer der geschachtelten Workflows für den anfänglichen aufrufenden Workflow nicht zugänglich ist. Weitere Informationen findest du unter Wiederverwenden von Workflows.

GITHUB_TOKEN-Berechtigungen müssen in geschachtelten Workflows identisch oder restriktiver sein. In der Workflowkette A > B > C gilt beispielsweise Folgendes: Wenn Workflow A über die Tokenberechtigung package: read verfügt, können B und C nicht die Berechtigung package: write aufweisen. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.

Informationen dazu, wie du mithilfe der API ermitteln kannst, welche Workflowdateien an einer bestimmten Workflowausführung beteiligt waren, findest du unter Überwachen der verwendeten Workflows.

Verwenden von Ausgaben eines wiederverwendbaren Workflows

Ein wiederverwendbarer Workflow generiert möglicherweise Daten, die du im aufrufenden Workflow verwenden möchtest. Damit du diese Ausgaben verwenden kannst, musst du sie als Ausgaben des wiederverwendbaren Workflows angeben.

Wenn ein wiederverwendbarer Workflow, der eine Ausgabe festlegt, mit einer Matrixstrategie ausgeführt wird, enthält die Ausgabe den Ausgabewert des letzten erfolgreich abgeschlossenen wiederverwendbaren Workflows der Matrix, der einen tatsächlichen Wert festlegt. Das bedeutet, wenn der letzte erfolgreich abgeschlossene wiederverwendbare Workflow eine leere Zeichenfolge als Ausgabe festlegt und der vorletzte erfolgreich abgeschlossene wiederverwendbare Workflow einen tatsächlichen Wert als Ausgabe festlegt, enthält die Ausgabe den Wert des vorletzten abgeschlossenen wiederverwendbaren Workflows.

Der folgende wiederverwendbare Workflow besteht aus einem Auftrag mit zwei Schritten. In jedem dieser Schritte wird ein einzelnes Wort als Ausgabe festgelegt: erst „hello“ und dann „world“. Im Abschnitt outputs des Auftrags werden diese Schrittausgaben den Auftragsausgaben output1 und output2 zugeordnet. Im Abschnitt on.workflow_call.outputs werden dann zwei Ausgaben für den Workflow selbst definiert, eine namens firstword, die output1 zugeordnet wird, und eine namens secondword, die output2 zugeordnet wird.

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

Nun können die Ausgaben im aufrufenden Workflow genau so verwendet werden wie die Ausgaben eines Auftrags im selben Workflow. Zum Verweisen auf die Ausgaben werden die auf Workflowebene im wiederverwendbaren Workflow definierten Namen firstword und secondword verwendet. In diesem Workflow wird in job1 der wiederverwendbare Workflow aufgerufen, und in job2 werden die Ausgaben des wiederverwendbaren Workflows („hello world“) in der Standardausgabe im Workflowprotokoll ausgegeben.

name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

Weitere Informationen zur Verwendung von Auftragsausgaben findest du unter Workflowsyntax für GitHub Actions. Wenn Sie etwas anderes als eine Variable (z. B. ein Buildartefakt) zwischen Workflows freigeben möchten, lesen Sie „Speichern von Workflowdaten als Artefakte“.

Überwachen der verwendeten Workflows

Du kannst die GitHub-REST-API verwenden, um zu überwachen, wie wiederverwendbare Workflows verwendet werden. Die Überwachungsprotokollaktion prepared_workflow_job wird ausgelöst, wenn ein Workflowauftrag gestartet wird. Zu den erfassten Daten gehören:

• repo: Dies ist die Organisation bzw. das Repository, in der bzw. dem der Workflowauftrag sich befindet. Bei einem Auftrag, in dem ein anderer Workflow aufgerufen wird, ist dies die Organisation bzw. das Repository des aufrufenden Workflows.

• @timestamp: Dies sind das Datum und die Uhrzeit des Starts des Auftrags im Unix-Epochenformat.

• job_name: Dies ist der Name des ausgeführten Auftrags.

• calling_workflow_refs : Ein Array von Dateipfaden für alle Aufruferworkflows, die an diesem Workflowauftrag beteiligt sind. Die Elemente im Array befinden sich nicht in der Reihenfolge, in der sie aufgerufen wurden, sondern in umgekehrter. In der Workflowkette „A > B > C“ wäre das Array beispielsweise beim Anzeigen der Protokolle für einen Auftrag in Workflow C ["octo-org/octo-repo/.github/workflows/B.yml", "octo-org/octo-repo/.github/workflows/A.yml"].

• calling_workflow_shas – ein Array von SHAs für alle Aufruferworkflows, die an diesem Workflowauftrag beteiligt sind. Das Array enthält die gleiche Anzahl von Elementen in derselben Reihenfolge wie das calling_workflow_refs-Array.

• job_workflow_ref: Dies ist die verwendete Workflowdatei im Format {owner}/{repo}/{path}/{filename}@{ref}. Bei einem Auftrag, in dem ein anderer Workflow aufgerufen wird, wird hiermit der aufgerufene Workflow angegeben.

Informationen zur Verwendung der REST-API zum Abfragen des Überwachungsprotokolls für eine Organisation findest du unter REST-API-Endpunkte für Organisationen.

Erneutes Ausführen von Workflows und Aufträgen mit wiederverwendbaren Workflows

Auf wiederverwendbare Workflows aus öffentlichen Repositorys kann mithilfe eines SHA, eines Releasetags oder eines Branchnamens verwiesen werden. Weitere Informationen findest du unter Wiederverwenden von Workflows.

Wenn du einen Workflow, der einen wiederverwendbaren Workflow verwendet, erneut ausführst, und der Verweis kein SHA-Verweis ist, sind einige Verhaltensweisen zu beachten:

• Bei erneuter Ausführung aller Aufträge in einem Workflow wird der wiederverwendbare Workflow aus dem angegebenen Verweis verwendet. Weitere Informationen zum erneuten Ausführen aller Aufträge in einem Workflow findest du unter Erneutes Ausführen von Workflows und Jobs.
• Beim erneuten Ausführen fehlerhafter Aufträge oder eines bestimmten Auftrags in einem Workflow wird der wiederverwendbare Workflow aus dem Commit-SHA des ersten Versuches verwendet. Weitere Informationen zum erneuten Ausführen fehlerhafter Aufträge in einem Workflow findest du unter Erneutes Ausführen von Workflows und Jobs. Weitere Informationen zum erneuten Ausführen eines bestimmten Auftrags in einem Workflow findest du unter Erneutes Ausführen von Workflows und Jobs.

Nächste Schritte

Weitere Informationen zu GitHub Actions findest du unter Ereignisse zum Auslösen von Workflows.

Du kannst Bereitstellungen standardisieren, indem du eine selbstgehostete Runnergruppe erstellst, die nur einen bestimmten wiederverwendbaren Workflow ausführen kann. Weitere Informationen findest du unter Verwalten des Zugriffs auf selbstgehostete Runner mithilfe von Gruppen.