Wiederverwenden von Workflowkonfigurationen

Wiederverwendbare Workflows

Referenzinformationen für wiederverwendbare Workflows

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 wird in einem öffentlichen Repository gespeichert auf GitHub Enterprise Server.

  Sie können wiederverwendbare Workflows, die für GitHub.com definiert sind, nicht direkt verwenden. Speichern Sie stattdessen eine Kopie des wiederverwendbaren Workflows, Ihre GitHub Enterprise Server-Instanceund rufen Sie den Workflow aus diesem Pfad auf.

• Der aufgerufene Workflow befindet sich in einem internen Repository, und die Einstellungen für dieses Repository ermöglichen den Zugriff darauf. Weitere Informationen finden Sie 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 finden Sie unter Freigeben von Aktionen und Workflows in deinem Unternehmen.

Die folgende Tabelle zeigt die Zugänglichkeit wiederverwendbarer Workflows für einen Aufrufer-Workflow, abhängig von der Sichtbarkeit des Host-Repositorys.

          `private`
          , `internal`und`public` |

| | | internal | internal und public | | | | public | public |

Die Actions Berechtigungen auf der Seite „Actions-Einstellungen“ des Aufrufer-Repositorys müssen so konfiguriert werden, dass die Nutzung von Aktionen und wiederverwendbaren Workflows ermöglicht wird. Weitere Informationen findest du unter Einstellung der GitHub Actions für ein Repository verwalten.

Für interne oder private Repositorys muss die Access-Richtlinie auf der Seite "Aktionen"-Einstellungen des repositorys des aufgerufenen Workflows explizit konfiguriert werden, um den Zugriff von Repositorys zuzulassen, die Aufruferworkflows enthalten - siehe Einstellung der GitHub Actions für ein Repository verwalten.

Einschränkungen von wiederverwendbaren Workflows

• Sie können bis zu vier Ebenen von Workflows verbinden. Weitere Informationen findest du unter Verschachteln wiederverwendbarer Workflows.

• Sie können maximal 20 eindeutige wiederverwendbare Workflows aus einer einzigen 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 Speichern von Informationen in Variablen und Kontextreferenz.

• 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 findest du unter Verwenden von Ausgaben eines wiederverwendbaren Workflows.

• 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 Speichern von Informationen in Variablen und Kontextreferenz.

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

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 finden Sie unter Workflowsyntax für GitHub Actions.
  • Die vom aufrufenden Workflow übergebene GITHUB_TOKEN-Berechtigungen können vom aufgerufenen Workflow nur herabgestuft (nicht erweitert) werden.
  • 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 }}, also wird, wenn Sie diesen Kontext als Wert in jobs.<job_id>.concurrency.group sowohl im aufrufenden als auch im aufgerufenen Workflow verwenden, der Aufrufer-Workflow abgebrochen, wenn der aufgerufene Workflow ausgeführt wird.

Wie wiederverwendbare Workflows Runner nutzen

GitHub-gehostete Runner

Die Zuweisung von GitHubgehosteten Runnern wird immer nur mit dem Kontext des Aufrufers ausgewertet. Die Abrechnung für GitHub-gehostete Runner ist immer mit dem Aufrufer verknüpft. Der Aufrufer-Workflow kann keine GitHub-gehosteten Runner vom aufgerufenen Repository verwenden. Weitere Informationen finden Sie unter Von GitHub gehostete Runner.

Selbstgehosteten Runnern

Aufgerufene Workflows, die demselben Benutzer, derselben Organisation oder demselben Unternehmen gehören wie der aufrufende Workflow, können über den Kontext des Aufrufers auf selbst gehostete 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.
• In der Organisation oder dem Unternehmen des aufrufenden Repositorys, sofern der Runner dem aufrufenden Repository zur Verfügung gestellt wurde

Zugriff und Berechtigungen für geschachtelte Workflows

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 Zugriff auf wiederverwendbare 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 finden Sie unter [AUTOTITLE](/actions/security-guides/automatic-token-authentication).

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

Verhalten von wiederverwendbaren Workflows beim erneuten Ausführen von Aufträgen

Auf wiederverwendbare Workflows aus öffentlichen Repositorys kann mithilfe eines SHA, eines Releasetags oder eines Branchnamens verwiesen werden. Weitere Informationen finden Sie 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.

Kontext github

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

Workflowvorlagen

Referenzinformationen, die beim Erstellen von Workflowvorlagen für deine Organisation verwendet werden sollen

Platzhalter $default-branch

Wenn du auf den Standardbranch eines Repositorys verweisen musst, kannst du in deiner Workflowvorlage den Platzhalter $default-branch verwenden. Wenn ein Workflow erstellt wird, wird der Platzhalter automatisch durch den Namen des Standardzweigs des Repositorys ersetzt.

Platzhalterwerte im Schlüssel runs-on

Die folgenden Werte im runs-on-Schlüssel werden auch als Platzhalter behandelt:

•         `ubuntu-latest` wird durch `[ self-hosted ]` ersetzt.
  

•         `windows-latest` wird durch `[ self-hosted, windows ]` ersetzt.
  

•         `macos-latest"` wird durch `[ self-hosted, macOS ]` ersetzt.
  

Beispieldatei für eine Workflowvorlage

Die Datei octo-organization-ci.yml veranschaulicht einen einfachen Workflow.

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Run a one-line script
        run: echo Hello from Octo Organization

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Run a one-line script
        run: echo Hello from Octo Organization

Anforderungen an Metadatendateien

Die Metadatendatei muss denselben Namen wie die Workflowdatei tragen, aber statt der .yml-Erweiterung muss .properties.json angefügt sein. Beispielsweise enthält die Datei octo-organization-ci.properties.json die Metadatei für den Workflow octo-organization-ci.yml:

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

•         `name`
           - 
          **Muss angegeben werden.** Der Name des Workflows. Dieser wird in der Liste der verfügbaren Workflows angezeigt.
  

•         `description`
           - 
          **Muss angegeben werden.** Die Beschreibung des Workflows. Dieser wird in der Liste der verfügbaren Workflows angezeigt.
  

•         `iconName`
           - 
          **Optional:** Legt ein Symbol für den Workflow fest, das in der Liste der Workflows angezeigt wird. 
          `iconName` kann eine der folgenden Typen sein:
  

  • Eine SVG-Datei, die im Verzeichnis workflow-templates gespeichert ist. Um auf eine Datei zu verweisen, muss der Wert dem Dateinamen ohne Dateierweiterung entsprechen. Beispielsweise wird auf eine SVG-Datei mit dem Namen example-icon.svg als example-icon verwiesen.
  • Ein Symbol aus der Octicon-Gruppe von GitHub. Um auf ein Octicon zu verweisen, muss der Wert octicon <icon name> lauten. Beispiel: octicon smiley.

•         `categories`
           - 
          **Optional:** Definiert die Kategorien, unter denen der Workflow angezeigt wird. Du kannst Kategorienamen aus den folgenden Listen verwenden:
  

  • Allgemeine Kategorienamen aus dem Repository starter-workflows.
  • Linguist-Sprachen aus der Liste im Repository linguist.
  • Unterstützte Technologiestapel aus der Liste im Repository starter-workflows.

•         `filePatterns`
           - 
          **Optional:** Dies ermöglicht die Verwendung des Workflows, wenn sich im Repository des Benutzers bzw. der Benutzerin eine Datei im Stammverzeichnis befindet, die einem definierten regulären Ausdruck entspricht.