Wiederverwenden von Workflows

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.

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.

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.

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

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 finden Sie unter Workflowsyntax für GitHub Actions.
```
jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.personal_access_token }}
        configuration-path: ${{ inputs.config-path }}
```
Im obigen Beispiel ist personal_access_token ein auf Repository- oder Organisationsebene definiertes Geheimnis.

Warnung

Umgebungsgeheimnisse können nicht vom aufrufenden Workflow übergeben werden, da on.workflow_call das Schlüsselwort environment nicht unterstützt. Wenn Sie environment in den wiederverwendbaren Workflow auf Auftragsebene einschließen, wird das Umgebungsgeheimnis verwendet und nicht das vom aufrufenden Workflow übergebene Geheimnis. Weitere Informationen findest du unter Verwalten von Umgebungen für die Bereitstellung und Workflowsyntax für GitHub Actions.
Ü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:
      personal_access_token: ${{ secrets.token }}
```
Workflows, die wiederverwendbare Workflows in derselben Organisation oder im selben Unternehmen aufrufen, können Geheimnisse mithilfe des Schlüsselworts inherit implizit ü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.

YAML

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 finden Sie unter Referenz zur sicheren Verwendung.

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. In diesem Schlüsselwort kannst Du keine Kontexte oder Ausdrücke verwenden.

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

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.

YAML

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

Ü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:
      personal_access_token: ${{ secrets.token }}

Workflows, die wiederverwendbare Workflows in derselben Organisation oder im selben Unternehmen aufrufen, können Geheimnisse mithilfe des Schlüsselworts inherit implizit ü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 Ausführen von Variationen von Aufträgen in einem Workflow.

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.

YAML

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

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

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.

Hinweis

Geschachtelte wiederverwendbare Workflows erfordern, dass der Aufrufer auf alle Workflows in der Kette zugreifen kann, und Berechtigungen können nur in der gesamten Kette beibehalten oder verringert – aber nicht erhöht – werden. Weitere Informationen finden Sie unter Referenz zu wiederverwendbaren Workflows.

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

YAML

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:
      repo-token: ${{ secrets.personal_access_token }} # pass just this secret

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

Der value muss auf den Wert einer Ausgabe auf Auftragsebene im aufgerufenen Workflow festgelegt werden. Ausgaben auf Schrittebene müssen zunächst den Ausgaben auf Auftragsebene zugeordnet werden, wie unten dargestellt.

Weitere Informationen findest du unter Übergeben von Informationen zwischen Jobs und Workflowsyntax für GitHub Actions.

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

YAML

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 du etwas anderes als eine Variable (z. B. ein Buildartefakt) zwischen Workflows freigeben möchtest, findest du weitere Informationen unter Store and share data with workflow artifacts.

Überwachen der verwendeten Workflows

Organisationen, die GitHub Enterprise Cloud verwenden, können über die GitHub-REST-API mit dem Überwachungsprotokoll interagieren, um zu überwachen, welche Workflows verwendet werden. Weitere Informationen findest du unter Dokumentation zu GitHub Enterprise Cloud.

Nächste Schritte

Informationen zu den Feinheiten bei der Wiederverwendung von Workflows findest du unter Referenz zu wiederverwendbaren Workflows.

Wiederverwenden von Workflows

In diesem Artikel