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.

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 Informationen zu von GitHub gehostete 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.

Einschränkungen

• In wiederverwendbaren Workflows können keine anderen wiederverwendbaren Workflows aufgerufen werden.
• Du kannst maximal 20 wiederverwendbare Workflows aus einer einzelnen Workflowdatei aufrufen.
• Wiederverwendbare Workflows, die in einem privaten Repository gespeichert sind, können nur von Workflows innerhalb desselben Repositorys verwendet werden. * Die strategy-Eigenschaft wird in keinem Auftrag unterstützt, der einen wiederverwendbaren Workflow aufruft.
• 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.
• 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.

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.

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

   Hinweis: Umgebungsgeheimnisse sind verschlüsselte Zeichenfolgen, die in einer von Ihnen für ein Repository definierten Umgebung gespeichert sind. Umgebungsgeheimnisse sind nur für Workflowaufträge verfügbar, die auf die entsprechende Umgebung verweisen. Weitere Informationen findest du unter Verwenden von Umgebungen für die Bereitstellung.

3. Ü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 }}

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

Zum Verweisen auf Dateien mit wiederverwendbaren Workflows wird eine der folgenden Syntaxoptionen verwendet:

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

{ref} kann ein SHA-Wert, ein Releasetag oder ein Branchname sein. Die Verwendung des Commit-SHA-Werts ist in Bezug auf Stabilität und Sicherheit am sichersten. 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 wieder aufrufende Workflow.

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

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

• jobs.<job_id>.if

• jobs.<job_id>.permissions

• jobs.<job_id>.concurrency

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

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

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.

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

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

Weitere Informationen zur Verwendung von Auftragsausgaben findest du unter Workflowsyntax für GitHub Actions.

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

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