Skip to main content

Workflowsyntax für GitHub Actions

Ein Workflow ist ein konfigurierbarer automatisierter Prozess, der aus mindestens einem Jobs besteht. Du musst eine YAML-Datei erstellen, um deine Workflowkonfiguration zu definieren.

In diesem Artikel

Informationen zur YAML-Syntax für Workflows

Workflowdateien verwenden die YAML-Syntax und müssen entweder die Dateierweiterung .yml oder .yaml aufweisen. Wenn du noch nicht mit YAML arbeitest und mehr erfahren möchtest, lies den Artikel zum Erlernen von YAML in Y Minuten.

Du musst Workflowdateien im .github/workflows-Verzeichnis deines Repositorys speichern.

name

Der Name des Workflows. GitHub zeigt die Namen deiner Workflows auf der Registerkarte „Aktionen“ deines Repositorys an. Wenn du name weglässt, zeigt GitHub den Workflowdateipfad relativ zum Stammverzeichnis des Repositorys an.

run-name

Der vom Workflow aus generierte Name für Workflowausführungen. GitHub zeigt den Namen der Workflowausführung in der Liste der Workflowausführungen auf der Registerkarte „Aktionen“ deines Repositorys an. Wenn run-name weggelassen wird oder nur aus Leerzeichen besteht, werden ereignisspezifische Informationen für die Workflowausführung für den Namen der Ausführung verwendet. Beispielsweise wird er für einen Workflow, der von einem push- oder pull_request-Ereignis ausgelöst wird, als Commitnachricht festgelegt.

Dieser Wert kann Ausdrücke enthalten und auf die Kontexte github und inputs verweisen.

Beispiel für run-name

run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}

on

Zum automatischen Auslösen eines Workflows definierst du mit on, welche Ereignisse eine Ausführung des Workflows verursachen. Eine Liste der verfügbaren Ereignisse findest du unter Ereignisse zum Auslösen von Workflows.

Du kannst einzelne oder mehrere Ereignisse definieren, die einen Workflow auslösen können, oder einen Zeitplan festlegen. Du kannst auch die Ausführung eines Workflows auf bestimmte Dateien, Tags oder Branchänderungen beschränken. Diese Optionen sind in den folgenden Abschnitten beschrieben.

Verwenden eines einzelnen Ereignisses

Beispielsweise wird ein Workflow mit dem folgenden on-Wert ausgeführt, wenn in einem beliebigen Branch im Repository des Workflows ein Push erfolgt:

on: push

Verwenden mehrerer Ereignisse

Du kannst ein einzelnes Ereignis oder mehrere Ereignisse angeben. Beispielsweise wird ein Workflow mit dem folgenden on-Wert ausgeführt, wenn in einem beliebigen Branch im Repository des Workflows ein Push erfolgt oder wenn jemand ein Repository forkt:

on: [push, fork]

Wenn du mehrere Ereignisse angibst, muss nur eines dieser Ereignisse auftreten, um deinen Workflow auszulösen. Treten gleichzeitig mehrere auslösende Ereignisaktivitätstypen für deinen Workflow auf, werden mehrere Workflow-Ausführungen ausgelöst.

Verwenden von Aktivitätstypen

Einige Ereignisse verfügen über Aktivitätstypen, die dir mehr Kontrolle darüber geben, wann dein Workflow ausgeführt werden soll. Verwende on.<event_name>.types, um die Art der Ereignisaktivität zu definieren, durch die eine Workflowausführung ausgelöst werden soll.

Das Ereignis issue_comment verfügt beispielsweise über die Aktivitätstypen created, edited und deleted. Wenn dein Workflow durch ein Ereignis vom Typ label ausgelöst wird, wird es ausgeführt, wenn eine Bezeichnung erstellt, bearbeitet oder gelöscht wird. Wenn du den Aktivitätstyp created für das Ereignis label angibst, wird der Workflow ausgeführt, wenn eine Bezeichnung erstellt wird, aber nicht, wenn eine Bezeichnung bearbeitet oder gelöscht wird.

on:
  label:
    types:
      - created

Bei Angabe mehrerer Aktivitätstypen wird dein Workflow ausgelöst, wenn einer dieser Ereignisaktivitätstypen auftritt. Treten gleichzeitig mehrere auslösende Ereignisaktivitätstypen für deinen Workflow auf, werden mehrere Workflowausführungen ausgelöst. Der folgende Workflow wird beispielsweise ausgelöst, wenn ein Issue erstellt oder beschriftet wird. Wenn ein Issue mit zwei Bezeichnungen erstellt wird, werden drei Workflowausführungen gestartet: eine für das Issue-Erstellungsereignis und zwei für die beiden Issue-Beschriftungsereignisse.

on:
  issues:
    types:
      - opened
      - labeled

Weitere Informationen zu den einzelnen Ereignissen und ihren Aktivitätstypen findest du unter Ereignisse zum Auslösen von Workflows.

Verwenden von Filtern

Einige Ereignisse verfügen über Filter, die Ihnen mehr Kontrolle darüber geben, wann Ihr Workflow ausgeführt werden soll.

Das push-Ereignis verfügt beispielsweise über einen branches-Filter. Dieser führt dazu, dass der Workflow nicht bei jedem beliebigen Push, sondern nur bei einem Push an einen Branch ausgeführt wird, der mit dem branches-Filter übereinstimmt.

on:
  push:
    branches:
      - main
      - 'releases/**'

Verwenden von Aktivitätstypen und Filtern mit mehreren Ereignissen

Wenn du Aktivitätstypen oder Filter für ein Ereignis und deine Workflowauslöser für mehrere Ereignisse angibst, musst du jedes Ereignis separat konfigurieren. Du musst einen Doppelpunkt (:) an alle Ereignisse anhängen, einschließlich Ereignisse ohne Konfiguration.

Beispielsweise wird ein Workflow mit dem folgenden on-Wert ausgeführt, wenn:

  • Eine Bezeichnung erstellt wird
  • Ein Push an die main-Verzweigung im Repository vorgenommen wird
  • Ein Push an eine GitHub Pages-aktivierte Verzweigung vorgenommen wird
on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Verwende on.<event_name>.types zum Definieren des Aktivitätstyps, der eine Workflowausführung auslöst. Die meisten GitHub-Ereignisse werden von mehreren Aktivitätstypen ausgelöst. Beispielsweise wird label ausgelöst, wenn für eine Bezeichnung eine der folgenden Aktivitäten durchgeführt wird: created, edited oder deleted. Mit dem Schlüsselwort types kannst du die Aktivitäten eingrenzen, durch die die Ausführung des Workflows ausgelöst wird. Wenn nur ein Aktivitätstyp ein Webhookereignis auslöst, ist das Schlüsselwort types unnötig.

Du kannst ein Array von types für Ereignisse verwenden. Weitere Informationen zu den einzelnen Ereignissen und ihren Aktivitätstypen findest du unter Ereignisse zum Auslösen von Workflows.

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

Wenn Du die Ereignisse pull_request und pull_request_target verwendest, kannst Du einen Workflow konfigurieren, der nur für Pull Requests ausgeführt werden kann, die auf bestimmte Branches abzielen.

Verwende den Filter branches, wenn Du Branchnamenmuster entweder einschließen oder ein- und ausschließen möchtest. Verwende den Filter branches-ignore, wenn du Branchnamenmuster nur ausschließen möchtest. Du kannst die Filter branches und branches-ignore nicht für dasselbe Ereignis in einem Workflow nutzen.

Wenn du sowohl branches/branches-ignore als auch paths/paths-ignore definierst, wird der Workflow nur ausgeführt, wenn beide Filter zutreffen.

Die Schlüsselwörter branches und branches-ignore akzeptieren Globmuster, die die Platzhalterzeichen *, **, +, ?, ! verwenden, um zu mehr als einem Branchnamen zu passen. Wenn ein Name eines dieser Zeichen enthält und Du eine literale Übereinstimmung wünscht, musst Du jedes dieser Sonderzeichen mit \ als Escapezeichen verwenden. Weitere Informationen zu Globmustern findest du unter Workflowsyntax für GitHub Actions.

Beispiel: Einschließen von Branches

Die in branches definierten Muster werden mit dem Namen des Git-Ref ausgewertet. Der folgende Workflow würde zum Beispiel immer dann ablaufen, wenn ein pull_request-Ereignis für einen Pull Request vorliegt:

  • Ein Branch namens main (refs/heads/main)
  • Ein Branch namens mona/octocat (refs/heads/mona/octocat)
  • Ein Branch, dessen Name mit releases/ beginnt, wie releases/10 (refs/heads/releases/10)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'

Sie sollten keine Pfad- oder Branchfilterung verwenden, um Workflowausführungen zu überspringen, wenn der Workflow vor der Zusammenführung durchlaufen werden muss. Weitere Informationen findest du unter Überspringen von Workflowausführungen und unter Verfügbare Regeln für Regelsätze.

Wenn ein Workflow aufgrund einer Branchfilterung, Pfadfilterung oder Commitnachricht übersprungen wird, verbleiben diesem Workflow zugeordnete Überprüfungen im Status „Ausstehend“. Ein Pull Request, bei dem diese Prüfungen erfolgreich sein müssen, wird vom Mergen ausgeschlossen.

Beispiel: Ausschließen von Branches

Wenn ein Muster dem Muster branches-ignore entspricht, wird der Workflow nicht ausgeführt. Die in branches-ignore definierten Muster werden mit dem Namen des Git-Ref ausgewertet. Der folgende Arbeitsablauf würde zum Beispiel immer dann ablaufen, wenn ein pull_request-Ereignis eintritt, es sei denn, der Pull Request ist zielgerichtet:

  • Ein Branch namens mona/octocat (refs/heads/mona/octocat)
  • Ein Branch, dessen Name mit releases/**-alpha übereinstimmt, wie releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'

Beispiel: Einschließen und Ausschließen von Branches

Du kannst dasselbe Ereignis nicht mit branches und branches-ignore in einem einzigen Workflow filtern. Wenn Du Branchmuster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchten, verwendest Du den Filter branches zusammen mit dem Zeichen !, um die auszuschließenden Branches anzugeben.

Wenn Du einen Branch mit dem Zeichen ! definierst, musst Du auch mindestens einen Branch ohne das Zeichen ! definieren. Wenn Du nur Branches ausschließen möchten, verwendest Du stattdessen branches-ignore.

Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.

  • Ein passendes negatives Muster (mit dem Präfix !) nach einer positiven Übereinstimmung schließt den Verweis auf Git aus.
  • Ein übereinstimmendes positives Muster nach einem negativen Abgleich schließt die Git-Ref wieder ein.

Der folgende Workflow wird bei pull_request-Ereignissen für Pull Requests ausgeführt, die auf releases/10 oder releases/beta/mona abzielen, aber nicht für Pull-Requests, die auf releases/10-alpha oder releases/beta/3-alpha abzielen, weil das negative Muster !releases/**-alpha auf das positive Muster folgt.

on:
  pull_request:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

Wenn du das push-Ereignis verwendest, kannst du einen Workflow so konfigurieren, dass er auf bestimmten Branches oder Tags ausgeführt wird.

Verwende den Filter branches, wenn du Branchnamenmuster entweder einschließen oder ein- und ausschließen möchtest. Verwende den Filter branches-ignore, wenn du Branchnamenmuster nur ausschließen möchtest. Du kannst die Filter branches und branches-ignore nicht für dasselbe Ereignis in einem Workflow nutzen.

Verwende den Filter tags, wenn du Tagnamenmuster entweder einschließen oder ein- und ausschließen möchtest. Verwende den Filter tags-ignore, wenn du Tagnamenmuster nur ausschließen möchtest. Du kannst die Filter tags und tags-ignore nicht für dasselbe Ereignis in einem Workflow nutzen.

Wenn du nur tags/tags-ignore oder nur branches/branches-ignore definierst, wird der Workflow nicht für Ereignisse ausgeführt, die sich auf die nicht definierten Git-Verweise auswirken. Wenn du weder tags/tags-ignore noch branches/branches-ignore definierst, wird der Workflow für Ereignisse ausgeführt, die sich entweder auf Branches oder Tags auswirken. Wenn du sowohl branches/branches-ignore als auch paths/paths-ignore definierst, wird der Workflow nur ausgeführt, wenn beide Filter zutreffen.

Die Schlüsselwörter branches, branches-ignore, tags und tags-ignore akzeptieren Globmuster, die die Zeichen *, **, +, ?, ! etc. verwenden, um mehr als einem Branch- oder Tagnamen zu entsprechen. Wenn ein Name eines dieser Zeichen enthält und du eine genaue Übereinstimmung möchtest, musst du jedes dieser Sonderzeichen mit \ versehen. Weitere Informationen zu Globmustern findest du unter Workflowsyntax für GitHub Actions.

Beispiel: Einschließen von Branches und Tags

Die in branches und tags definierten Muster werden anhand des Namens des Git-Verweises ausgewertet. Der folgende Workflow wird beispielsweise jedes Mal ausgeführt, wenn ein push-Ereignis an folgende Instanzen ausgeführt wird:

  • Ein Branch namens main (refs/heads/main)
  • Ein Branch namens mona/octocat (refs/heads/mona/octocat)
  • Ein Branch, dessen Name mit releases/ beginnt, wie releases/10 (refs/heads/releases/10)
  • Ein Tag namens v2 (refs/tags/v2)
  • Ein Tag, dessen Name mit v1. beginnt, wie v1.9.1 (refs/tags/v1.9.1)
on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v2
      - v1.*

Beispiel: Ausschließen von Branches und Tags

Wenn ein Muster dem Muster branches-ignore oder tags-ignore entspricht, wird der Workflow nicht ausgeführt. Die in branches und tags definierten Muster werden anhand des Namens des Git-Verweises ausgewertet. Der folgende Workflow wird beispielsweise immer dann ausgeführt, wenn ein push-Ereignis auftritt, es sei denn, das push-Ereignis wird an folgende Instanzen ausgeführt:

  • Ein Branch namens mona/octocat (refs/heads/mona/octocat)
  • Ein Branch, dessen Name mit releases/**-alpha übereinstimmt, wie releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)
  • Ein Tag namens v2 (refs/tags/v2)
  • Ein Tag, dessen Name mit v1. beginnt, wie v1.9 (refs/tags/v1.9)
on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:        
      - v2
      - v1.*

Beispiel: Einschließen und Ausschließen von Branches und Tags

Du kannst branches und branches-ignore nicht verwenden, um dasselbe Ereignis in einem einzigen Workflow zu filtern. Ebenso kannst du tags und tags-ignore nicht verwenden, um dasselbe Ereignis in einem einzigen Workflow zu filtern. Wenn du Branch- oder Tagmuster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchtest, verwende den Filter branches oder tags zusammen mit dem Zeichen !, um die auszuschließenden Branches und Tags anzugeben.

Wenn du einen Branch mit dem Zeichen ! definierst, musst du auch mindestens einen Branch ohne das Zeichen ! definieren. Wenn du nur Branches ausschließen möchtest, verwende stattdessen branches-ignore. Wenn du ebenfalls einen Tag mit dem Zeichen ! definierst, musst du auch mindestens einen Tag ohne das Zeichen ! definieren. Wenn du nur Tags ausschließen möchtest, verwende stattdessen tags-ignore.

Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.

  • Ein passendes negatives Muster (mit dem Präfix !) nach einer positiven Übereinstimmung schließt den Verweis auf Git aus.
  • Ein übereinstimmendes positives Muster nach einem negativen Abgleich schließt die Git-Ref wieder ein.

Der folgenden Workflow führt Pushes an releases/10 oder releases/beta/mona aus, aber nicht an releases/10-alpha oder releases/beta/3-alpha, da das negative Muster !releases/**-alpha dem positiven Muster folgt.

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

Wenn du die Ereignisse push und pull_request verwendest, kannst du einen Workflow konfigurieren, der basierend auf den geänderten Dateipfaden ausgeführt wird. Bei Push-Vorgängen zu Tags werden Pfadfilter nicht ausgewertet.

Verwende den Filter paths, wenn du Dateipfadmuster entweder einschließen oder einschließen und ausschließen möchtest. Verwende den Filter paths-ignore, wenn du Dateipfadmuster nur ausschließen möchtest. Du kannst die Filter paths und paths-ignore nicht für dasselbe Ereignis in einem Workflow nutzen. Wenn Pfadmuster für ein einzelnes Ereignis sowohl eingeschlossen als auch ausgeschlossen werden sollen, benutzen Sie den Filter paths mit dem vorangestellten Zeichen !, um die auszuschließenden Pfade anzugeben.

Hinweis: Die Reihenfolge, in der paths-Muster definiert werden, ist entscheidend:

  • Ein passendes negatives Muster mit dem Präfix ! nach einem positiven Abgleich schließt den Pfad aus.
  • Ein passendes positives Muster nach einem negativen Abgleich schließt den Pfad wieder ein.

Wenn du sowohl branches/branches-ignore als auch paths/paths-ignore definierst, wird der Workflow nur ausgeführt, wenn beide Filter zutreffen.

Die Schlüsselwörter paths und paths-ignore akzeptieren Globmuster, die die Platzhalterzeichen * und ** verwenden, um zu mehr als einem Pfadnamen zu passen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

Beispiel: Einschließen von Pfaden

Wenn mindestens ein Pfad zu einem Muster im Filter paths passt, wird der Workflow ausgeführt. Der folgende Workflow wird beispielsweise jedes Mal ausgeführt, wenn du eine JavaScript-Datei (.js) pushst.

on:
  push:
    paths:
      - '**.js'

Sie sollten keine Pfad- oder Branchfilterung verwenden, um Workflowausführungen zu überspringen, wenn der Workflow vor der Zusammenführung durchlaufen werden muss. Weitere Informationen findest du unter Überspringen von Workflowausführungen und unter Verfügbare Regeln für Regelsätze.

Wenn ein Workflow aufgrund von Pfadfilterung, Branchfilterung oder einer Commitnachricht übersprungen wird, verbleiben diesem Workflow zugeordnete Überprüfungen im Status „Ausstehend“. Ein Pull Request, bei dem diese Prüfungen erfolgreich sein müssen, wird vom Mergen ausgeschlossen.

Beispiel: Ausschließen von Pfaden

Wenn alle Pfadnamen mit Mustern in paths-ignore übereinstimmen, wird der Workflow nicht ausgeführt. Wenn manche Pfadnamen nicht mit Mustern in paths-ignore übereinstimmen, wird der Workflow ausgeführt, obwohl einige Pfadnamen den Mustern entsprechen.

Ein Workflow mit dem folgenden Pfadfilter wird nur bei push-Ereignissen ausgeführt, bei denen sich mindestens eine Datei außerhalb des Verzeichnisses docs im Stamm des Repositorys befindet.

on:
  push:
    paths-ignore:
      - 'docs/**'

Beispiel: Einschließen und Ausschließen von Pfaden

Du kannst dasselbe Ereignis nicht mit paths und paths-ignore in einem einzigen Workflow filtern. Wenn Pfadmuster für ein einzelnes Ereignis sowohl eingeschlossen als auch ausgeschlossen werden sollen, benutzen Sie den Filter paths mit dem vorangestellten Zeichen !, um die auszuschließenden Pfade anzugeben.

Wenn du einen Pfad mit dem Zeichen ! definierst, musst du auch mindestens einen Pfad ohne das Zeichen ! definieren. Wenn du nur Pfade ausschließen möchtest, verwende stattdessen paths-ignore.

Die Reihenfolge, in der paths-Muster definiert werden, ist entscheidend:

  • Ein passendes negatives Muster mit dem Präfix ! nach einem positiven Abgleich schließt den Pfad aus.
  • Ein passendes positives Muster nach einem negativen Abgleich schließt den Pfad wieder ein.

In diesem Beispiel wird jedes Mal ausgeführt, wenn das Ereignis push eine Datei im Verzeichnis sub-project oder in seinen Unterverzeichnissen enthält, es sei denn, die Datei befindet sich im Verzeichnis sub-project/docs. Beispielsweise löst in Push, der sub-project/index.js oder sub-project/src/index.js geändert hat, die Ausführung eines Workflows aus, dies geschieht jedoch nicht, wenn nur sub-project/docs/readme.md geändert wurde.

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git-Diff-Vergleiche

Hinweis: Wenn der Push-Vorgang mehr als 1.000 Commits umfasst oder wenn GitHub die Diff wegen einer Zeitüberschreitung nicht erzeugt, wird der Workflow immer ausgeführt.

Um zu ermitteln, ob ein Workflow ausgeführt werden soll, wertet der Filter die geänderten Dateien anhand der Listen paths-ignore oder paths aus. Wurden keine Dateien geändert, wird der Workflow nicht ausgeführt.

GitHub erzeugt die Liste der geänderten Dateien mithilfe von „Two-Dot-Diffs“ (Vergleiche mittels 2 Punkt-Syntax „..“) für Push-Vorgänge und „Three-Dot-Diffs“ (Vergleiche mittels 3 Punkt-Syntax „...“) für Pull-Requests:

  • Pull Requests: Three-Dot-Diffs ziehen den Vergleich zwischen der neuesten Version des Topic-Branch und des Commit, bei dem der Topic-Branch zuletzt mit dem Basis-Branch synchronisiert wurde.
  • Push-Vorgänge an bestehende Branches: Eine Two-Dot-Diff vergleicht die Head- und Basis-SHAs direkt miteinander.
  • Push-Vorgänge an neue Branches: Eine Two-Dot-Diff wird zum übergeordneten Element des Vorgängers des tiefsten Commits gepusht.

Diffs sind auf 300 Dateien beschränkt. Wenn Dateien geändert werden, die nicht mit den ersten 300 vom Filter zurückgegebenen Dateien übereinstimmen, wird der Workflow nicht ausgeführt. Du musst eventuell genauere Filter erstellen, damit der Workflow automatisch ausgeführt wird.

Weitere Informationen findest du unter Informationen zum Vergleich von Branches in Pull Requests.

on.schedule

Mithilfe von on.schedule kannst du einen Zeitplan für deine Workflows definieren. Mithilfe der POSIX-Cron-Syntax kannst du einen Workflow so planen, dass er zu bestimmten UTC-Zeiten ausgeführt wird. Geplante Workflows laufen auf dem jüngsten Commit auf dem Standard- oder Basisbranch. Das kürzeste Intervall, in dem Du geplante Workflows ausführen kannst, ist einmal alle 5 Minuten.

In diesem Beispiel wird der Workflow jeden Tag um 5:30 Uhr und 17:30 Uhr UTC ausgelöst:

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

Ein einzelner Workflow kann durch mehrere schedule-Ereignisse ausgelöst werden. Über den Kontext github.event.schedule kannst du auf das Zeitplanereignis zugreifen, das den Workflow ausgelöst hat. In diesem Beispiel wird der Workflow von Montag bis Donnerstag um 5:30 Uhr UTC gestartet, wobei der Schritt Not on Monday or Wednesday am Montag und Mittwoch übersprungen wird.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

Weitere Informationen zur Cron-Syntax findest du unter Ereignisse zum Auslösen von Workflows.

on.workflow_call

Verwende on.workflow_call, um die Eingaben und Ausgaben für einen wiederverwendbaren Workflow zu definieren. Du kannst dem aufgerufenen Workflow auch die verfügbaren Geheimnisse zuordnen. Weitere Informationen zu wiederverwendbaren Workflows findest du unter Wiederverwenden von Workflows.

on.workflow_call.inputs

Wenn du das Schlüsselwort workflow_call verwendest, kannst du optional Eingaben angeben, die vom Aufruferworkflow an den aufgerufenen Workflow übergeben werden. Weitere Informationen zum Schlüsselwort workflow_call findest du unter Ereignisse zum Auslösen von Workflows.

Zusätzlich zu den verfügbaren Standardeingabeparametern erfordert on.workflow_call.inputs auch einen type-Parameter. Weitere Informationen findest du unter on.workflow_call.inputs.<input_id>.type.

Wenn kein default-Parameter festgelegt ist, entspricht der Standardwert der Eingabe false für einen booleschen Wert, 0 für eine Zahl und "" für eine Zeichenfolge.

Innerhalb des aufgerufenen Workflows kannst du den inputs-Kontext verwenden, um auf eine Eingabe zu verweisen. Weitere Informationen findest du unter Kontexte.

Wenn ein Aufruferworkflow eine Eingabe übergibt, die nicht im aufgerufenen Workflow angegeben ist, führt dies zu einem Fehler.

Beispiel für on.workflow_call.inputs

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

Weitere Informationen findest du unter Wiederverwenden von Workflows.

on.workflow_call.inputs.<input_id>.type

Diese Angabe ist erforderlich, wenn die Eingabe für das Schlüsselwort on.workflow_call definiert ist. Der Wert dieses Parameters ist eine Zeichenfolge, die den Datentyp der Eingabe angibt. Dies muss boolean, number oder string entsprechen.

on.workflow_call.outputs

Hierbei handelt es sich um eine Zuordnung der Ausgaben für einen aufgerufenen Workflow. Die Ausgaben des aufgerufenen Workflows sind für alle Downstreamaufträge im Aufruferworkflow verfügbar. Jede Ausgabe verfügt über einen Bezeichner, eine optionale description, und einen value.. Der value muss auf den Wert einer Ausgabe aus einem Auftrag innerhalb des aufgerufenen Workflows festgelegt werden.

Im folgenden Beispiel werden zwei Ausgaben für diesen wiederverwendbaren Workflow definiert: workflow_output1 und workflow_output2. Diese werden den Ausgaben namens job_output1 und job_output2 zugeordnet, die beide von einem Auftrag namens my_job stammen.

Beispiel für on.workflow_call.outputs

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

Weitere Informationen zum Verweisen auf eine Auftragsausgabe findest du unter jobs.<job_id>.outputs. Weitere Informationen findest du unter Wiederverwenden von Workflows.

on.workflow_call.secrets

Dies ist eine Zuordnung der Geheimnisse, die im aufgerufenen Workflow verwendet werden können.

Innerhalb des aufgerufenen Workflows kannst du den secrets-Kontext verwenden, um auf ein Geheimnis zu verweisen.

Hinweis: Wenn du das Geheimnis an einen geschachtelten wiederverwendbaren Workflow übergibst, musst du jobs.<job_id>.secrets erneut verwenden, um das Geheimnis zu übergeben. Weitere Informationen findest du unter Wiederverwenden von Workflows.

Wenn ein Aufruferworkflow ein Geheimnis übergibt, das nicht im aufgerufenen Workflow angegeben ist, führt dies zu einem Fehler.

Beispiel für on.workflow_call.secrets

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:

  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
    # passing the secret to an action
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

  # passing the secret to a nested reusable workflow
  pass-secret-to-workflow:
    uses: ./.github/workflows/my-workflow
    secrets:
       token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

Dies ist ein Zeichenfolgenbezeichner, der dem Geheimnis zugeordnet werden soll.

on.workflow_call.secrets.<secret_id>.required

Dies ist ein boolescher Wert, der angibt, ob das Geheimnis angegeben werden muss.

on.workflow_run.<branches|branches-ignore>

Wenn du das workflow_run-Ereignis verwendest, kannst du angeben, in welchen Branches der auslösende Workflow ausgeführt werden muss, um deinen Workflow auszulösen.

Die Filter branches und branches-ignore akzeptieren Globmuster, die die Platzhalterzeichen *, **, +, ?, ! und andere verwenden, um zu mehr als einem Branch-Namen zu passen. Wenn ein Name eines dieser Zeichen enthält und du eine literale Übereinstimmung wünscht, musst du für jedes dieser Sonderzeichen mit Escape mit \ verwenden. Weitere Informationen zu Globmustern findest du unter Workflowsyntax für GitHub Actions.

Beispielsweise wird ein Workflow mit dem folgenden Trigger nur ausgeführt, wenn der Workflow namens Build in einem Branch namens releases/ ausgeführt wird.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

Beispielsweise wird ein Workflow mit dem folgenden Trigger nur ausgeführt, wenn der Workflow namens Build in einem Branch namens canary ausgeführt wird:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

Du kannst die Filter branches und branches-ignore nicht für dasselbe Ereignis in einem Workflow nutzen. Wenn du Branch-Muster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchtest, verwende den branches-Filter zusammen mit dem !-Zeichen, um die auszuschließenden Branches anzugeben.

Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.

  • Ein passendes negatives Muster (Präfix !) nach einem positiven Abgleich schließt die Branch aus.
  • Ein passendes positives Muster nach einem negativen Abgleich schließt die Branch wieder ein.

Beispielsweise wird ein Workflow mit dem folgenden Trigger nur ausgeführt, wenn der Workflow namens Build in einem Branch namens releases/10 oder releases/beta/mona, aber nicht releases/10-alpha, releases/beta/3-alpha oder main ausgeführt wird.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch

Bei Verwendung des workflow_dispatch-Ereignisses kannst du optional Eingaben angeben, die an den Workflow übergeben werden.

Dieser Trigger empfängt nur Ereignisse, wenn sich die Workflow-Datei auf dem Standardbranch befindet.

on.workflow_dispatch.inputs

Der ausgelöste Workflow empfängt die Eingaben im inputs-Kontext. Weitere Informationen findest du unter Kontexte.

Hinweise:

  • Der Workflow empfängt auch die Eingaben im github.event.inputs-Kontext. Die Informationen im Kontext inputs und github.event.inputs sind identisch, außer dass der Kontext inputs boolesche Werte als solche beibehält, anstatt sie in Zeichenfolgen zu konvertieren. Der Typ choice wird in eine Zeichenfolge aufgelöst und ist eine einzelne auswählbare Option.
  • Die maximale Anzahl von Eigenschaften auf oberster Ebene für inputs beträgt 10.
  • Die maximale Länge der Nutzdaten für inputs beträgt 65.535 Zeichen.

Beispiel für on.workflow_dispatch.inputs

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

on.workflow_dispatch.inputs.<input_id>.required

Dies ist ein boolescher Wert, der angibt, ob die Eingabe angegeben werden muss.

on.workflow_dispatch.inputs.<input_id>.type

Der Wert dieses Parameters ist eine Zeichenfolge, die den Datentyp der Eingabe angibt. Dieser muss boolean, choice, number, environment oder string entsprechen.

permissions

Du kannst permissions verwenden, um die Standardberechtigungen zu ändern, die dem GitHub-Token (GITHUB_TOKEN) gewährt werden. So kannst du Zugriff nach Bedarf hinzufügen oder entfernen, um nur den mindestens erforderlichen Zugriff zu gewähren. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.

permissions kann entweder als Schlüssel auf oberster Ebene verwendet werden, um für alle Aufträge im Workflow zu gelten, oder innerhalb bestimmter Aufträge. Wenn du den Schlüssel permissions innerhalb eines bestimmten Auftrags hinzufügst, werden die von dir angegebenen Zugriffsrechte auf alle Aktionen und Ausführungsbefehle innerhalb dieses Auftrags angewendet, die das GitHub-Token (GITHUB_TOKEN) verwenden. Weitere Informationen findest du unter jobs.<job_id>.permissions.

Für jeden der verfügbaren Bereiche, die in der folgenden Tabelle dargestellt sind, kannst du eine der Berechtigungen zuweisen: read, writeoder none. Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none festgelegt.

Verfügbare Bereiche und Einzelheiten dazu, was sie einer Aktion jeweils erlauben:

ScopeErlaubt einer Aktion die Verwendung von GITHUB_TOKEN zum
actionsArbeiten mit GitHub Actions. actions: write ermöglicht einer Aktion beispielsweise das Abbrechen einer Workflowausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
checksArbeiten mit Überprüfungsausführungen und Überprüfungssammlungen. checks: write ermöglicht einer Aktion beispielsweise das Erstellen einer Überprüfungsausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
contentsArbeiten mit den Inhalten des Repositorys. contents: read ermöglicht einer Aktion beispielsweise das Auflisten der Commits, und contents:write ermöglicht der Aktion das Erstellen eines Releases. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
deploymentsArbeiten mit Bereitstellungen. deployments: write ermöglicht einer Aktion beispielsweise das Erstellen einer neuen Bereitstellung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
discussionsArbeiten mit GitHub Discussions. discussions: write ermöglicht einer Aktion beispielsweise das Schließen oder Löschen einer Diskussion. Weitere Informationen findest du unter Verwenden der GraphQL-API für Diskussionen.
id-tokenAbrufen eines OIDC-Tokens (OpenID Connect). Dies erfordert id-token: write. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect
issuesArbeiten mit Issues. issues: write ermöglicht einer Aktion beispielsweise das Hinzufügen eines Kommentars zu einem Issue. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
packagesArbeiten mit GitHub Packages. packages: write ermöglicht einer Aktion beispielsweise das Hochladen und Veröffentlichen von Paketen auf GitHub Packages. Weitere Informationen findest du unter Informationen zu Berechtigungen für GitHub-Pakete.
pagesArbeiten mit GitHub Pages. pages: write ermöglicht einer Aktion beispielsweise das Anfordern eines GitHub Pages-Builds. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
pull-requestsArbeiten mit Pull Requests. pull-requests: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Bezeichnung zu einem Pull Request. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
repository-projectsArbeiten mit GitHub-Projekten (klassisch). repository-projects: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Spalte zu einem Projekt (klassisch). Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
security-eventsArbeiten mit GitHub-Codeüberprüfungen und Dependabot-Warnungen. security-events: read ermöglicht einer Aktion beispielsweise das Auflisten der Dependabot-Warnungen für das Repository, und security-events: write ermöglicht einer Aktion, den Status einer Codeüberprüfungswarnung zu aktualisieren. Weitere Informationen findest du unter Repositoryberechtigungen für „Codeüberprüfungswarnungen“ und Repositoryberechtigungen für „Dependabot-Warnungen“ in „Für GitHub Apps erforderliche Berechtigungen“.
statusesArbeiten mit Commitstatus. statuses:read ermöglicht einer Aktion beispielsweise das Auflisten der Commitstatus für einen bestimmten Verweis. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.

Definieren des Zugriffs für die GITHUB_TOKEN-Bereiche

Du kannst den Zugriff definieren, den das GITHUB_TOKEN zulässt, indem du read, write oder none als Wert der verfügbaren Bereiche innerhalb des permissions-Schlüssels angibst.

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none festgelegt.

Du kannst die folgende Syntax verwenden, um einen der read-all- oder write-all-Zugriffe für alle verfügbaren Reservierungsumfänge zu definieren:

permissions: read-all
permissions: write-all

Du kannst die folgende Syntax verwenden, um Berechtigungen für alle verfügbaren Bereiche zu deaktivieren:

permissions: {}

Ändern der Berechtigungen in einem geforkten Repository

Darüber hinaus kannst du den permissions-Schlüssel verwenden, um Leseberechtigungen für geforkte Repositorys hinzuzufügen oder zu entfernen, aber in der Regel kannst du keinen Schreibzugriff gewähren. Eine Ausnahme für dieses Verhalten besteht dann, wenn ein Administratorbenutzer die Option Schreibtoken an Workflows aus Pull Requests senden in den GitHub Actions-Einstellungen ausgewählt hat. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.

Festlegen der GITHUB_TOKEN-Berechtigungen für alle Aufträge in einem Workflow

Du kannst permissions auf der obersten Ebene eines Workflows angeben, sodass die Einstellung für alle Aufträge im Workflow gilt.

Beispiel: Festlegen der GITHUB_TOKEN-Berechtigungen für einen gesamten Workflow

In diesem Beispiel wird gezeigt, wie Berechtigungen für das GitHub-Token (GITHUB_TOKEN) festgelegt werden, die für alle Aufträge im Workflow gelten. Bei allen Berechtigungen handelt es sich um die Gewährung von Lesezugriff.

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

Dies ist eine map von Variablen, die für die Schritte aller Aufträge im Workflow verfügbar sind. Du kannst auch Variablen festlegen, die nur für die Schritte eines einzelnen Auftrags oder für einen einzelnen Schritt verfügbar sind. Weitere Informationen findest du unter jobs.<job_id>.env und jobs.<job_id>.steps[*].env.

Variablen in der env-Zuordnung können nicht in Bezug auf andere Variablen in der Zuordnung definiert werden.

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.

Beispiel für env

env:
  SERVER: production

defaults

Verwende defaults, um eine map der Standardeinstellungen zu erstellen, die für alle Aufträge im Workflow gelten. Du kannst auch Standardeinstellungen festlegen, die nur für einen Job verfügbar sind. Weitere Informationen findest du unter jobs.<job_id>.defaults.

Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.

defaults.run

Du kannst defaults.run verwenden, um Standardoptionen für shell und working-directory für alle run-Schritte in einem Workflow bereitzustellen. Du kannst auch Standardeinstellungen für run festlegen, die nur für einen Auftrag verfügbar sind. Weitere Informationen findest du unter jobs.<job_id>.defaults.run. In diesem Schlüsselwort kannst Du keine Kontexte oder Ausdrücke verwenden.

Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.

Beispiel: Festlegen der Standardshell und des Arbeitsverzeichnisses

defaults:
  run:
    shell: bash
    working-directory: ./scripts

concurrency

Verwende concurrency, um sicherzustellen, dass immer nur ein einziger Auftrag oder Workflow mit derselben Parallelitätsgruppe ausgeführt wird. Eine Parallelitätsgruppe kann eine beliebige Zeichenfolge oder ein beliebiger Ausdruck sein. Der Ausdruck kann nur die Kontexte github, inputs und vars verwenden. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.

Du kannst concurrency auch auf Auftragsebene angeben. Weitere Informationen findest du unter jobs.<job_id>.concurrency.

Wenn ein gleichzeitiger Auftrag oder ein Workflow in die Warteschlange gestellt wird, wenn ein anderer Auftrag oder eine andere Workflowausführungen, der bzw. die dieselbe Übereinstimmungsgruppe im Repository verwendet, in Bearbeitung ist, wird pending der Warteschlangeauftrag oder die Workflowausführung. Alle ausstehenden Jobs oder Workflowausführungen, die in derselben Parallelitätsgruppe ausgeführt werden, werden abgebrochen, wenn ein neuer Auftrag oder eine Workflowausführung in die Warteschlange gestellt wird. Sie können auch mit cancel-in-progress: true alle derzeit ausgeführten Aufträge oder Workflowausführungen in derselben Parallelitätsgruppe abbrechen.

Hinweise:

  • Beim Namen von Parallelitätsgruppen wird die Groß-/Kleinschreibung nicht berücksichtigt. Beispielsweise werden prod und Prod als dieselbe Parallelitätsgruppe betrachtet.
  • Die Sortierung ist für Aufträge oder Workflowausführungen mit Parallelitätsgruppen nicht garantiert. Aufträge oder Workflowausführungen werden in derselben Parallelitätsgruppe in einer beliebigen Reihenfolge behandelt.

Beispiel: Verwenden der Parallelität und des Standardverhaltens

Das Standardverhalten von GitHub Actions erlaubt die gleichzeitige Ausführung mehrerer Aufträge bzw. Workflow-Läufe. Mit dem Schlüsselwort concurrency können Sie die Nebenläufigkeit von Workflow-Läufen steuern.

Sie können das Schlüsselwort concurrency zum Beispiel unmittelbar nach der Definition von Auslösebedingungen verwenden, um die Nebenläufigkeit ganzer Workflow-Läufe für eine bestimmte Verzweigung zu begrenzen:

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Sie können auch die Parallelität von Aufträgen innerhalb eines Workflows begrenzen, indem Sie das Schlüsselwort concurrency auf Auftragsebene verwenden:

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

Beispiel: Parallelitätsgruppen

Parallelitätsgruppen bieten eine Möglichkeit zum Verwalten und Einschränken der Ausführung von Workflowausführungen oder Aufträgen, die denselben Parallelitätsschlüssel aufweisen.

Der concurrency-Schlüssel wird verwendet, um Workflows oder Aufträge in einer Parallelitätsgruppe zu gruppieren. Wenn Sie einen concurrency-Schlüssel definieren, stellt GitHub Actions sicher, dass immer nur ein Workflow oder Auftrag mit diesem Schlüssel ausgeführt wird. Wenn ein neuer Workflow oder Job mit demselben concurrency-Schlüssel gestartet wird, bricht GitHub Actions jeden bereits laufenden Workflow oder Job mit diesem Schlüssel ab. Der concurrency-Schlüssel kann eine hartcodierte Zeichenfolge oder ein dynamischer Ausdruck sein, der Kontextvariablen enthält.

Es ist möglich, Parallelitätsbedingungen in Ihrem Workflow zu definieren, sodass der Workflow oder Auftrag zum Teil einer Parallelitätsgruppe wird.

Dies bedeutet, dass GitHub, wenn ein Workflow ausgeführt oder Auftrag gestartet wird, alle Workflowausführungen oder Aufträge abbricht, die bereits in derselben Parallelitätsgruppe ausgeführt werden. Dies ist in Szenarien hilfreich, in denen Sie parallele Ausführungen für einen bestimmten Satz von Workflows oder Aufträgen verhindern möchten, z. B. die für Bereitstellungen in einer Stagingumgebung verwendeten, um Aktionen zu verhindern, die Konflikte verursachen oder mehr Ressourcen verbrauchen könnten, als nötig.

In diesem Beispiel ist job-1 Teil einer Parallelitätsgruppe mit dem Namen staging_environment. Dies bedeutet, dass, wenn eine neue Ausführung job-1 ausgelöst wird, alle Läufe desselben Auftrags in der bereits ausgeführten staging_environment-Parallelitätsgruppe abgebrochen werden.

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

Alternativ bedeutet die Verwendung eines dynamischen Ausdrucks wie concurrency: ci-${{ github.ref }} in Ihrem Workflow, dass der Workflow oder Auftrag Teil einer Parallelitätsgruppe mit dem Namen ci- gefolgt von der Referenz der Verzweigung bzw. des Tags, der den Workflow ausgelöst hat, ist. Wenn in diesem Beispiel ein neuer Commit an die Standard-Verzweigung übertragen wird, während eine vorherige Ausführung noch ausgeführt wird, wird die vorherige Ausführung abgebrochen, und die neue gestartet:

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Beispiel: Verwenden von Parallelität zum Abbrechen eines In-Progress-Auftrags oder Ausführens

Um Parallelität zum Abbrechen eines laufenden Auftrags zu verwenden oder in GitHub Actions auszuführen, können Sie den concurrency-Schlüssel mit der cancel-in-progress-Option auf true verwenden:

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Beachten Sie, dass in diesem Beispiel, ohne eine bestimmte Parallelitätsgruppe zu definieren, GitHub Actions jegliche laufende Ausführung eines Auftrags oder Workflows abbricht.

Beispiel: Verwenden eines Fallbackwerts

Wenn du den Gruppennamen mit einer Eigenschaft erstellst, die nur für bestimmte Ereignisse definiert ist, kannst du einen Fallbackwert verwenden. So wird beispielsweise github.head_ref nur für pull_request Ereignisse definiert. Wenn dein Workflow zusätzlich pull_request zu Ereignissen auf andere Ereignisse reagiert, musst du einen Fallback bereitstellen, um einen Syntaxfehler zu vermeiden. Die folgende Parallelitätsgruppe bricht laufende Aufträge oder Ausführungen nur bei pull_request Ereignissen ab. Wenn github.head_ref nicht definiert ist, greift die Parallelitätsgruppe auf die Ausführungs-ID zurück, die garantiert eindeutig und für die Ausführung definiert ist.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Beispiel: Nur laufende Aufträge oder Ausführungen für den aktuellen Workflow abbrechen

Wenn du mehrere Workflows im selben Repository hast, müssen die Namen der Parallelitätsgruppen für alle Workflows eindeutig sein, um zu vermeiden, dass laufende Aufträge oder Ausführungen von anderen Workflows abgebrochen werden. Andernfalls werden alle zuvor ausgeführten oder ausstehenden Aufgaben abgebrochen, unabhängig vom Workflow.

Um nur die Ausführung desselben Workflows abzubrechen, kannst du die github.workflow Eigenschaft verwenden, um die Parallelitätsgruppe zu erstellen:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs

Eine Workflowausführung besteht aus einem oder mehreren jobs, die standardmäßig parallel ausgeführt werden. Um Aufträge nacheinander auszuführen, kannst du mit dem Schlüsselwort jobs.<job_id>.needs Abhängigkeiten von anderen Aufträgen definieren.

Jeder Auftrag wird in einer durch runs-on festgelegten Runnerumgebung ausgeführt.

Innerhalb der Nutzungsbeschränkungen des Workflows kannst Du unbegrenzt viele Jobs ausführen. Weitere Informationen zu auf GitHub gehosteten Runnern findest du unter Nutzungseinschränkungen, Abrechnung und Verwaltung und zu Nutzungseinschränkungen für selbstgehostete Runner unter Informationen zu selbstgehosteten Runnern.

Wenn du den eindeutigen Bezeichner eines Auftrags in einer Workflowausführung ermitteln musst, kannst du die GitHub-API verwenden. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub Actions.

jobs.<job_id>

Verwende jobs.<job_id>, um deinem Auftrag einen eindeutigen Bezeichner zu geben. Der Schlüssel job_id ist ein String und der Wert umfasst eine Zuordnung der Konfigurationsdaten für den Auftrag. Du musst <job_id> mit einer Zeichenfolge ersetzen, die für das jobs-Objekt eindeutig ist. <job_id> muss mit einem Buchstaben oder _ beginnen und darf nur alphanumerische Zeichen, - oder _ enthalten.

Beispiel: Erstellen von Aufträgen

In diesem Beispiel wurden zwei Aufträge erstellt und ihre job_id-Werte sind my_first_job und my_second_job.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

Mit jobs.<job_id>.name legst du einen Namen für den Auftrag fest, der auf der Benutzeroberfläche von GitHub angezeigt wird.

jobs.<job_id>.permissions

Du kannst für einen spezifischen Auftrag jobs.<job_id>.permissions verwenden, um die Standardberechtigungen zu ändern, die demGITHUB_TOKEN gewährt werden, und können so den Zugriff nach Bedarf hinzufügen oder entfernen, um nur den erforderlich Mindestzugriff zu gewähren. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.

Wenn du die Berechtigung in einer Auftragsdefinition angibst, kannst du bei Bedarf einen anderen Satz von Berechtigungen für die GITHUB_TOKEN für jeden Auftrag konfigurieren. Alternativ kannst du die Berechtigungen für alle Aufträge im Workflow angeben. Informationen zum Definieren von Berechtigungen auf Workflow-Ebene findest du unter permissions.

Für jeden der verfügbaren Bereiche, die in der folgenden Tabelle dargestellt sind, kannst du eine der Berechtigungen zuweisen: read, writeoder none. Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none festgelegt.

Verfügbare Bereiche und Einzelheiten dazu, was sie einer Aktion jeweils erlauben:

ScopeErlaubt einer Aktion die Verwendung von GITHUB_TOKEN zum
actionsArbeiten mit GitHub Actions. actions: write ermöglicht einer Aktion beispielsweise das Abbrechen einer Workflowausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
checksArbeiten mit Überprüfungsausführungen und Überprüfungssammlungen. checks: write ermöglicht einer Aktion beispielsweise das Erstellen einer Überprüfungsausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
contentsArbeiten mit den Inhalten des Repositorys. contents: read ermöglicht einer Aktion beispielsweise das Auflisten der Commits, und contents:write ermöglicht der Aktion das Erstellen eines Releases. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
deploymentsArbeiten mit Bereitstellungen. deployments: write ermöglicht einer Aktion beispielsweise das Erstellen einer neuen Bereitstellung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
discussionsArbeiten mit GitHub Discussions. discussions: write ermöglicht einer Aktion beispielsweise das Schließen oder Löschen einer Diskussion. Weitere Informationen findest du unter Verwenden der GraphQL-API für Diskussionen.
id-tokenAbrufen eines OIDC-Tokens (OpenID Connect). Dies erfordert id-token: write. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect
issuesArbeiten mit Issues. issues: write ermöglicht einer Aktion beispielsweise das Hinzufügen eines Kommentars zu einem Issue. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
packagesArbeiten mit GitHub Packages. packages: write ermöglicht einer Aktion beispielsweise das Hochladen und Veröffentlichen von Paketen auf GitHub Packages. Weitere Informationen findest du unter Informationen zu Berechtigungen für GitHub-Pakete.
pagesArbeiten mit GitHub Pages. pages: write ermöglicht einer Aktion beispielsweise das Anfordern eines GitHub Pages-Builds. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
pull-requestsArbeiten mit Pull Requests. pull-requests: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Bezeichnung zu einem Pull Request. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
repository-projectsArbeiten mit GitHub-Projekten (klassisch). repository-projects: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Spalte zu einem Projekt (klassisch). Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.
security-eventsArbeiten mit GitHub-Codeüberprüfungen und Dependabot-Warnungen. security-events: read ermöglicht einer Aktion beispielsweise das Auflisten der Dependabot-Warnungen für das Repository, und security-events: write ermöglicht einer Aktion, den Status einer Codeüberprüfungswarnung zu aktualisieren. Weitere Informationen findest du unter Repositoryberechtigungen für „Codeüberprüfungswarnungen“ und Repositoryberechtigungen für „Dependabot-Warnungen“ in „Für GitHub Apps erforderliche Berechtigungen“.
statusesArbeiten mit Commitstatus. statuses:read ermöglicht einer Aktion beispielsweise das Auflisten der Commitstatus für einen bestimmten Verweis. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen.

Definieren des Zugriffs für die GITHUB_TOKEN-Bereiche

Du kannst den Zugriff definieren, den das GITHUB_TOKEN zulässt, indem du read, write oder none als Wert der verfügbaren Bereiche innerhalb des permissions-Schlüssels angibst.

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none festgelegt.

Du kannst die folgende Syntax verwenden, um einen der read-all- oder write-all-Zugriffe für alle verfügbaren Reservierungsumfänge zu definieren:

permissions: read-all
permissions: write-all

Du kannst die folgende Syntax verwenden, um Berechtigungen für alle verfügbaren Bereiche zu deaktivieren:

permissions: {}

Ändern der Berechtigungen in einem geforkten Repository

Darüber hinaus kannst du den permissions-Schlüssel verwenden, um Leseberechtigungen für geforkte Repositorys hinzuzufügen oder zu entfernen, aber in der Regel kannst du keinen Schreibzugriff gewähren. Eine Ausnahme für dieses Verhalten besteht dann, wenn ein Administratorbenutzer die Option Schreibtoken an Workflows aus Pull Requests senden in den GitHub Actions-Einstellungen ausgewählt hat. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.

Beispiel: Festlegen der GITHUB_TOKEN-Berechtigungen für einen Auftrag in einem Workflow

In diesem Beispiel werden Berechtigungen angezeigt, die für den GITHUB_TOKEN eingestellt werden, der nur für den Auftrag namens stale angewendet werden. Der Schreibzugriff wird für die issues- und pull-requests-Bereiche gewährt. Alle anderen Bereiche haben keinen Zugriff.

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5

jobs.<job_id>.needs

Verwende jobs.<job_id>.needs, um alle Aufträge zu identifizieren, die erfolgreich abgeschlossen sein müssen, bevor dieser Auftrag ausgeführt wird. Hier ist ein String oder ein Array mit Strings zulässig. Wenn ein Auftrag fehlschlägt oder übersprungen wird, werden alle Aufträge übersprungen, die diesen Auftrag benötigen, außer die Aufträge umfassen einen bedingte Ausdruck, mit dem der Auftrag dennoch fortgesetzt wird. Wenn eine Ausführung eine Reihe von Aufträgen enthält, die voneinander abhängig sind, wird ein Fehler oder eine Auslassung auf alle Aufträge in der Abhängigkeitskette ab dem Fehler- oder Auslassungspunkt angewendet. Wenn ein Auftrag auch dann ausgeführt werden soll, wenn ein Auftrag, von dem er abhängig ist, nicht erfolgreich war, verwenden Sie den bedingten always()-Ausdruck in jobs.<job_id>.if.

Beispiel: Erfordern erfolgreicher abhängiger Aufträge

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

In diesem Beispiel muss job1 erfolgreich abgeschlossen sein, bevor job2 beginnt, und job3 wartet darauf, dass job1 und job2 angeschlossen werden.

Die Aufträge in diesem Beispiel werden sequenziell ausgeführt:

  1. job1
  2. job2
  3. job3

Beispiel: Nicht Erfordern erfolgreicher abhängiger Aufträge

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

In diesem Beispiel verwendet job3 den bedingten Ausdruck always(), sodass er immer nach Abschluss von job1 und job2 ausgeführt wird, unabhängig davon, ob sie erfolgreich waren. Weitere Informationen findest du unter Ausdrücke.

jobs.<job_id>.if

Mit der Bedingung jobs.<job_id>.if kannst du dafür sorgen, dass ein Schritt nur ausgeführt wird, wenn eine Bedingung erfüllt ist. Du kannst eine Bedingung mit jedem unterstützten Kontext und Ausdruck erstellen. Weitere Informationen dazu, welche Kontexte in diesem Schlüssel unterstützt werden, findest du unter Kontexte.

Hinweis: Die jobs.<job_id>.if Bedingung wird ausgewertet, bevor jobs.<job_id>.strategy.matrix sie angewendet wird.

Wenn du Ausdrücke in einer if-Bedingung verwendest, kannst du optional die ${{ }}-Ausdruckssyntax weglassen, da GitHub Actions die if-Bedingung automatisch als Ausdruck wertet. Diese Ausnahme gilt jedoch nicht überall.

Du musst immer die Syntax des ${{ }}-Ausdrucks verwenden oder mit '', "" oder () abbrechen, wenn der Ausdruck mit ! beginnt, da ! die reservierte Schreibweise im YAML-Format ist. Beispiel:

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

Weitere Informationen findest du unter Ausdrücke.

Beispiel: Ausführen eines Auftrags nur für bestimmte Repositorys

In diesem Beispiel wird if verwendet, um zu steuern, wann der Auftrag production-deploy ausgeführt werden kann. Er wird nur ausgeführt, wenn das Repository octo-repo-prod heißt und sich innerhalb der Organisation octo-org befindet. Andernfalls wird der Auftrag als übersprungen markiert.

YAML
name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

Verwende jobs.<job_id>.runs-on zum Definieren des Computertyps, auf dem der Auftrag ausgeführt werden soll.

: Der Zielcomputer kann ein auf GitHub gehosteter Runner, ein größerer Runner oder ein selbstgehosteter Runner sein. : Du kannst Runner basierend auf den ihnen zugewiesenen Bezeichnungen oder ihrer Gruppenmitgliedschaft oder einer Kombination aus diesen als Ziel festlegen.

  • Du kannst runs-on als Folgendes angeben:

    • als einzelne Zeichenfolge
    • als einzelne Variable, die eine Zeichenfolge enthält
    • als ein Array von Zeichenfolgen, als Variablen, die Zeichenfolgen enthalten, oder als eine Kombination aus diesen beiden Optionen
    • ein key: value Paar, das die Tasten group verwendet labels
  • Wenn du ein Array von Zeichenfolgen oder Variablen angibst, wird dein Workflow auf jedem Runner ausgeführt, der allen angegebenen runs-on-Werten entspricht. Hier wird der Auftrag beispielsweise nur auf einem selbstgehosteten Runner mit den Bezeichnungen linux, x64 und gpuausgeführt:

    runs-on: [self-hosted, linux, x64, gpu]
    

    Weitere Informationen findest du unter Auswählen von selbstgehosteten Runnern.

  • Du kannst Zeichenfolgen und Variablen in einem Array mischen. Beispiel:

    on:
      workflow_dispatch:
        inputs:
          chosen-os:
            required: true
            type: choice
            options:
            - Ubuntu
            - macOS
    
    jobs:
      test:
        runs-on: [self-hosted, "${{ inputs.chosen-os }}"]
        steps:
        - run: echo Hello world!
    
  • Wenn du deinen Workflow auf mehreren Computern ausführen möchtest, verwende jobs.<job_id>.strategy.

Hinweis: Anführungszeichen sind für einfache Zeichenfolgen wie z. B. self-hosted nicht erforderlich, aber sie sind für Ausdrücke wie "${{ inputs.chosen-os }}" erforderlich.

Auswählen von GitHub-gehosteten Runnern

Wenn du einen GitHub-gehosteten Runner verwendest, läuft jeder Job in einer neuen Instanz eines von runs-on angegebenen Runner-Images.

Verfügbare Bezeichnungen von GitHub-gehostete Runnern sind:

OS (YAML-Workflow-Kennzeichnung) Hinweise
ubuntu-latest, ubuntu-22.04, ubuntu-20.04 Die ubuntu-latest-Bezeichnung verwendet derzeit das Ubuntu 22.04-Runner-Image.
windows-latest, windows-2022, windows-2019 Die windows-latest-Bezeichnung verwendet derzeit das Windows 2022-Runner-Image.
macos-latest, macos-14 [Beta], macos-13, macos-12, macos-11 Die macos-latest-Workflowbezeichnung verwendet derzeit das macOS 12-Runnerimage.

Weitere Informationen zu Spezifikationen von auf GitHub gehosteten Runnern findest du unter Informationen zu von GitHub gehostete Runnern.

Hinweis: Die -latest-Runner-Images sind die neuesten stabilen Images, die GitHub bereitstellt, und entsprechen möglicherweise nicht der neuesten Version des Betriebssystems, die beim Betriebssystemanbieter erhältlich ist.

Warnung: Beta- und veraltete Images werden „wie gesehen“, „mit allen Mängeln“ und „wie verfügbar“ bereitgestellt und sind von der Vereinbarung zum Servicelevel und der Garantie ausgeschlossen. Beta-Images werden möglicherweise nicht vom Kundendienst abgedeckt.

Beispiel: Angeben eines Betriebssystems

runs-on: ubuntu-latest

Weitere Informationen findest du unter Verwenden von auf GitHub gehosteten Runnern.

Auswählen von selbstgehosteten Runnern

Um einen selbstgehosteten Runner für deinen Auftrag anzugeben, konfiguriere runs-on in deiner Workflowdatei mit Bezeichnungen selbstgehosteter Runner.

Alle selbstgehosteten Runner weisen die Bezeichnung self-hosted auf. Wenn du nur diese Bezeichnung verwendest, werden dadurch alle selbstgehosteten Runner ausgewählt. Um Runner auszuwählen, die bestimmte Kriterien erfüllen, z. B. im Hinblick auf Betriebssystem oder Architektur, empfehlen wir die Angabe eines Arrays von Bezeichnungen, das mit self-hosted beginnt (diese Bezeichnung muss als Erstes aufgeführt werden) und dann nach Bedarf weitere Bezeichnungen einschließt. Wenn du ein Array von Bezeichnungen angibst, werden Aufträge in die Warteschlange von Runnern eingereiht, die alle von dir angegebenen Bezeichnungen aufweisen.

Die Bezeichnung self-hosted ist zwar nicht erforderlich, wird aber bei Verwendung selbstgehosteter Runner dringend empfohlen. So wird sichergestellt, dass in deinem Auftrag nicht versehentlich aktuelle oder zukünftige von GitHub gehostete Runner angegeben werden.

Beispiel: Verwenden von Bezeichnungen für die Auswahl von Runnern

runs-on: [self-hosted, linux]

Weitere Informationen findest du unter Informationen zu selbstgehosteten Runnern und unter Verwenden von selbstgehosteten Runnern in einem Workflow.

Auswählen von Runnern in einer Gruppe

Du kannst runs-on verwenden, um Runnergruppen als Ziel zu verwenden, sodass der Auftrag auf jedem Runner ausgeführt wird, der Mitglied dieser Gruppe ist. Für eine präzisere Steuerung kannst du auch Runnergruppen mit Bezeichnungen kombinieren.

Runnergruppen können nur größerer Runner oder selbstgehostete Runner als Mitglieder haben.

Beispiel: Verwenden von Gruppen zum Steuern, wo Aufträge ausgeführt werden

In diesem Beispiel wurden Ubuntu-Runner zu einer Gruppe namens ubuntu-runners hinzugefügt. Der runs-on-Schlüssel sendet den Auftrag an einen beliebigen verfügbaren Runner in der Gruppe ubuntu-runners:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: ubuntu-runners
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

Beispiel: Kombinieren von Gruppen und Bezeichnungen

Wenn du Gruppen und Bezeichnungen kombinierst, muss der Runner beide Anforderungen erfüllen, um zum Ausführen des Auftrags berechtigt zu sein.

In diesem Beispiel wird eine Runnergruppe namens ubuntu-runners mit Ubuntu-Runnern aufgefüllt, denen zudem die Bezeichnung ubuntu-20.04-16core zugewiesen wurde. Der runs-on-Schlüssel kombiniert group und labels, sodass der Auftrag an einen beliebigen verfügbaren Runner innerhalb der Gruppe weitergeleitet wird, der auch eine übereinstimmende Bezeichnung aufweist:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

Beispiel: Verwenden von Präfixen zum Unterscheiden von Runnergruppen

Wenn du beispielsweise eine Runnergruppe mit dem Namen my-group in der Organisation und eine andere Gruppe mit dem Namen my-group im Unternehmen hast, kannst du deine Workflowdatei aktualisieren, sodass org/my-group oder ent/my-group verwendet wird, um zwischen den beiden Gruppen zu unterscheiden.

Verwenden von org/:

runs-on:
  group: org/my-group
  labels: [ self-hosted, label-1 ]

Verwenden von ent/:

runs-on:
  group: ent/my-group
  labels: [ self-hosted, label-1 ]

jobs.<job_id>.environment

Verwende jobs.<job_id>.environment zum Definieren der Umgebung, auf die der Auftrag verweist. Alle Umgebungsschutzregeln müssen erfüllt sein, bevor ein Auftrag, der auf die Umgebung verweist, an einen Runner gesendet wird. Weitere Informationen findest du unter Verwenden von Umgebungen für die Bereitstellung.

Du kannst die Umgebung nur mit dem name-Wert oder als Umgebungsobjekt mit name und url bereitstellen. Die URL entspricht environment_url ist in der Bereitstellungs-API. Weitere Informationen zu den Bereitstellungs-API findest du unter REST-API-Endpunkte für Repositorys.

Beispiel: Verwenden eines einzelnen Umgebungsnamens

environment: staging_environment

Beispiel: Verwenden von Umgebungsnamen und URL

environment:
  name: production_environment
  url: https://github.com

Der Wert von url kann ein Ausdruck sein. Zulässiger Ausdruckskontext: github, inputs, vars, needs, strategy, matrix, job, runner und env. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.

Beispiel: Verwenden der Ausgabe als URL

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

Der Wert von name kann ein Ausdruck sein. Zulässiger Ausdruckskontext: github, inputs, vars, needs, strategy und matrix. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.

Beispiel: Verwenden eines Ausdrucks als Umgebungsname

environment:
  name: ${{ github.ref_name }}

jobs.<job_id>.concurrency

Du kannst jobs.<job_id>.concurrency verwenden, um sicherzustellen, dass immer nur ein einzelner Auftrag oder Workflow mit der gleichen Parallelitätsgruppe ausgeführt wird. Eine Parallelitätsgruppe kann eine beliebige Zeichenfolge oder ein beliebiger Ausdruck sein. Zulässiger Ausdruckskontext: github, inputs, vars, needs, strategy und matrix. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.

concurrency kann auch auf Workflowebene angegeben werden. Weitere Informationen findest du unter concurrency.

Wenn ein gleichzeitiger Auftrag oder ein Workflow in die Warteschlange gestellt wird, wenn ein anderer Auftrag oder eine andere Workflowausführungen, der bzw. die dieselbe Übereinstimmungsgruppe im Repository verwendet, in Bearbeitung ist, wird pending der Warteschlangeauftrag oder die Workflowausführung. Alle ausstehenden Jobs oder Workflowausführungen, die in derselben Parallelitätsgruppe ausgeführt werden, werden abgebrochen, wenn ein neuer Auftrag oder eine Workflowausführung in die Warteschlange gestellt wird. Sie können auch mit cancel-in-progress: true alle derzeit ausgeführten Aufträge oder Workflowausführungen in derselben Parallelitätsgruppe abbrechen.

Hinweise:

  • Beim Namen von Parallelitätsgruppen wird die Groß-/Kleinschreibung nicht berücksichtigt. Beispielsweise werden prod und Prod als dieselbe Parallelitätsgruppe betrachtet.
  • Die Sortierung ist für Aufträge oder Workflowausführungen mit Parallelitätsgruppen nicht garantiert. Aufträge oder Workflowausführungen werden in derselben Parallelitätsgruppe in einer beliebigen Reihenfolge behandelt.

Beispiel: Verwenden der Parallelität und des Standardverhaltens

Das Standardverhalten von GitHub Actions erlaubt die gleichzeitige Ausführung mehrerer Aufträge bzw. Workflow-Läufe. Mit dem Schlüsselwort concurrency können Sie die Nebenläufigkeit von Workflow-Läufen steuern.

Sie können das Schlüsselwort concurrency zum Beispiel unmittelbar nach der Definition von Auslösebedingungen verwenden, um die Nebenläufigkeit ganzer Workflow-Läufe für eine bestimmte Verzweigung zu begrenzen:

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Sie können auch die Parallelität von Aufträgen innerhalb eines Workflows begrenzen, indem Sie das Schlüsselwort concurrency auf Auftragsebene verwenden:

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

Beispiel: Parallelitätsgruppen

Parallelitätsgruppen bieten eine Möglichkeit zum Verwalten und Einschränken der Ausführung von Workflowausführungen oder Aufträgen, die denselben Parallelitätsschlüssel aufweisen.

Der concurrency-Schlüssel wird verwendet, um Workflows oder Aufträge in einer Parallelitätsgruppe zu gruppieren. Wenn Sie einen concurrency-Schlüssel definieren, stellt GitHub Actions sicher, dass immer nur ein Workflow oder Auftrag mit diesem Schlüssel ausgeführt wird. Wenn ein neuer Workflow oder Job mit demselben concurrency-Schlüssel gestartet wird, bricht GitHub Actions jeden bereits laufenden Workflow oder Job mit diesem Schlüssel ab. Der concurrency-Schlüssel kann eine hartcodierte Zeichenfolge oder ein dynamischer Ausdruck sein, der Kontextvariablen enthält.

Es ist möglich, Parallelitätsbedingungen in Ihrem Workflow zu definieren, sodass der Workflow oder Auftrag zum Teil einer Parallelitätsgruppe wird.

Dies bedeutet, dass GitHub, wenn ein Workflow ausgeführt oder Auftrag gestartet wird, alle Workflowausführungen oder Aufträge abbricht, die bereits in derselben Parallelitätsgruppe ausgeführt werden. Dies ist in Szenarien hilfreich, in denen Sie parallele Ausführungen für einen bestimmten Satz von Workflows oder Aufträgen verhindern möchten, z. B. die für Bereitstellungen in einer Stagingumgebung verwendeten, um Aktionen zu verhindern, die Konflikte verursachen oder mehr Ressourcen verbrauchen könnten, als nötig.

In diesem Beispiel ist job-1 Teil einer Parallelitätsgruppe mit dem Namen staging_environment. Dies bedeutet, dass, wenn eine neue Ausführung job-1 ausgelöst wird, alle Läufe desselben Auftrags in der bereits ausgeführten staging_environment-Parallelitätsgruppe abgebrochen werden.

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

Alternativ bedeutet die Verwendung eines dynamischen Ausdrucks wie concurrency: ci-${{ github.ref }} in Ihrem Workflow, dass der Workflow oder Auftrag Teil einer Parallelitätsgruppe mit dem Namen ci- gefolgt von der Referenz der Verzweigung bzw. des Tags, der den Workflow ausgelöst hat, ist. Wenn in diesem Beispiel ein neuer Commit an die Standard-Verzweigung übertragen wird, während eine vorherige Ausführung noch ausgeführt wird, wird die vorherige Ausführung abgebrochen, und die neue gestartet:

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Beispiel: Verwenden von Parallelität zum Abbrechen eines In-Progress-Auftrags oder Ausführens

Um Parallelität zum Abbrechen eines laufenden Auftrags zu verwenden oder in GitHub Actions auszuführen, können Sie den concurrency-Schlüssel mit der cancel-in-progress-Option auf true verwenden:

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Beachten Sie, dass in diesem Beispiel, ohne eine bestimmte Parallelitätsgruppe zu definieren, GitHub Actions jegliche laufende Ausführung eines Auftrags oder Workflows abbricht.

Beispiel: Verwenden eines Fallbackwerts

Wenn du den Gruppennamen mit einer Eigenschaft erstellst, die nur für bestimmte Ereignisse definiert ist, kannst du einen Fallbackwert verwenden. So wird beispielsweise github.head_ref nur für pull_request Ereignisse definiert. Wenn dein Workflow zusätzlich pull_request zu Ereignissen auf andere Ereignisse reagiert, musst du einen Fallback bereitstellen, um einen Syntaxfehler zu vermeiden. Die folgende Parallelitätsgruppe bricht laufende Aufträge oder Ausführungen nur bei pull_request Ereignissen ab. Wenn github.head_ref nicht definiert ist, greift die Parallelitätsgruppe auf die Ausführungs-ID zurück, die garantiert eindeutig und für die Ausführung definiert ist.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Beispiel: Nur laufende Aufträge oder Ausführungen für den aktuellen Workflow abbrechen

Wenn du mehrere Workflows im selben Repository hast, müssen die Namen der Parallelitätsgruppen für alle Workflows eindeutig sein, um zu vermeiden, dass laufende Aufträge oder Ausführungen von anderen Workflows abgebrochen werden. Andernfalls werden alle zuvor ausgeführten oder ausstehenden Aufgaben abgebrochen, unabhängig vom Workflow.

Um nur die Ausführung desselben Workflows abzubrechen, kannst du die github.workflow Eigenschaft verwenden, um die Parallelitätsgruppe zu erstellen:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

Du kannst jobs.<job_id>.outputs verwenden, um eine map von Ausgaben für einen Auftrag zu erstellen. Ausgaben eines Jobs stehen allen nachgelagerten Jobs zur Verfügung, die von diesem Job abhängen. Weitere Informationen zum Definieren von Auftragsabhängigkeiten findest du unter jobs.<job_id>.needs.

Ausgaben sind Unicode-Zeichenfolgen und können maximal 1 MB groß sein. Die Gesamtanzahl aller Ausgaben in einer Workflowausführung kann maximal 50 MB betragen.

Ausgaben von Aufträgen, die Ausdrücke enthalten, werden am Ende jedes Auftrags auf dem Runner ausgewertet. Ausgaben, die Geheimnisse enthalten, werden auf dem Runner zensiert und nicht an GitHub Actions gesendet.

Um Auftragsausgaben in einem abhängigen Auftrag zu verwenden, kannst du den needs-Kontext verwenden. Weitere Informationen finden Sie unter Kontexte.

Hinweis: $GITHUB_OUTPUT wird zwischen allen Schritten in einem Job geteilt. Wenn Sie denselben Ausgabenamen in mehreren Schritten verwenden, setzt der letzte Schritt zum Schreiben in die Ausgabe den Wert außer Kraft. Wenn Ihr Job eine Matrix verwendet und in $GITHUB_OUTPUT schreibt, wird der Inhalt für jede Matrixkombination überschrieben. Sie können den matrix Kontext verwenden, um eindeutige Ausgabenamen für jede Job-Konfiguration zu erstellen. Weitere Informationen finden Sie unter Kontexte.

Beispiel: Definieren von Ausgaben für einen Auftrag

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "test=hello" >> "$GITHUB_OUTPUT"
      - id: step2
        run: echo "test=world" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

jobs.<job_id>.env

Dies ist eine map von Variablen, die für alle Schritte im Auftrag verfügbar sind. Du kannst Variablen für den gesamten Workflow oder für einen einzelnen Schritt festlegen. Weitere Informationen findest du unter env und jobs.<job_id>.steps[*].env.

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.

Beispiel für jobs.<job_id>.env

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Verwende jobs.<job_id>.defaults, um eine map mit Standardeinstellungen zu erstellen, die für alle Schritte im Auftrag gelten. Du kannst auch Standardeinstellungen für den gesamten Workflow festlegen. Weitere Informationen findest du unter defaults.

Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.

jobs.<job_id>.defaults.run

Verwende jobs.<job_id>.defaults.run, um für alle run-Schritte im Auftrag eine Standardeinstellung für shell und working-directory bereitzustellen. Dieses Schlüsselwort kann auf mehrere Kontexte verweisen. Weitere Informationen findest du unter Kontexte.

Du kannst für shell und working-directory Standardoptionen für alle run-Schritte in einem Auftrag bereitstellen. Außerdem kannst du für den gesamten Workflow Standardeinstellungen für run festlegen. Weitere Informationen findest du unter defaults.run.

Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.

Beispiel: Festlegen von Standardoptionen für den run-Schritt für einen Auftrag

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: ./scripts

jobs.<job_id>.steps

Ein Auftrag enthält eine Sequenz von Aufgaben (als steps bezeichnet). Mit Schritten können Befehle oder Einrichtungsaufgaben ausgeführt werden, und außerdem Aktionen, die sich in deinem Repository oder in einem öffentlichen Repository befinden oder in einer Docker Registry veröffentlicht sind. Nicht alle Schritte führen Aktionen aus, doch alle Aktionen werden als Schritt ausgeführt. Jeder Schritt wird in einem eigenen Prozess in der Runner-Umgebung ausgeführt. Er hat Zugriff auf den Arbeitsbereich und das Dateisystem. Da die Schritte jeweils in einem eigenen Prozess laufen, werden Änderungen an den Umgebungsvariablen nicht von einem Schritt zum nächsten beibehalten. GitHub umfasst integrierte Schritte zum Einrichten und Ausführen eines Jobs.

GitHub zeigt nur die ersten 1.000 Prüfungen an. Sie können jedoch eine unbegrenzte Anzahl von Schritten ausführen, solange Sie sich innerhalb der Grenzwerte für die Workflownutzung befinden. Weitere Informationen zu auf GitHub gehosteten Runnern findest du unter Nutzungseinschränkungen, Abrechnung und Verwaltung und zu Nutzungseinschränkungen für selbstgehostete Runner unter Informationen zu selbstgehosteten Runnern.

Beispiel für jobs.<job_id>.steps

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

Eine eindeutige Kennung für den Schritt. Du kannst mit id auf den Schritt in Kontexten verweisen. Weitere Informationen findest du unter Kontexte.

jobs.<job_id>.steps[*].if

Du kannst die if-Bedingung verwenden, um zu verhindern, dass ein Schritt ausgeführt wird – es sei denn, eine Bedingung ist erfüllt. Du kannst eine Bedingung mit jedem unterstützten Kontext und Ausdruck erstellen. Weitere Informationen dazu, welche Kontexte in diesem Schlüssel unterstützt werden, findest du unter Kontexte.

Wenn du Ausdrücke in einer if-Bedingung verwendest, kannst du optional die ${{ }}-Ausdruckssyntax weglassen, da GitHub Actions die if-Bedingung automatisch als Ausdruck wertet. Diese Ausnahme gilt jedoch nicht überall.

Du musst immer die Syntax des ${{ }}-Ausdrucks verwenden oder mit '', "" oder () abbrechen, wenn der Ausdruck mit ! beginnt, da ! die reservierte Schreibweise im YAML-Format ist. Beispiel:

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

Weitere Informationen findest du unter Ausdrücke.

Beispiel: Verwenden von Kontexten

Dieser Schritt wird nur ausgeführt, wenn der Ereignistyp pull_request und die Ereignisaktion unassigned lautet.

steps:
  - name: My first step
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
    run: echo This event is a pull request that had an assignee removed.

Beispiel: Verwenden von Funktionen zur Statusüberprüfung

my backup step wird nur ausgeführt, wenn beim vorherigen Schritt eines Auftrags ein Fehler auftritt. Weitere Informationen findest du unter Ausdrücke.

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

Beispiel: Verwenden von Geheimnissen

Auf Geheimnisse kann nicht direkt in if:-Bedingungen verwiesen werden. Erwäge stattdessen, Geheimnisse als Umgebungsvariablen auf Auftragsebene festzulegen, und verweise dann auf die Umgebungsvariablen, um Schritte im Auftrag bedingt auszuführen.

Wenn kein Geheimnis festgelegt wurde, ist der Rückgabewert eines Ausdrucks, der auf das Geheimnis verweist (z. B. ${{ secrets.SuperSecret }} im Beispiel), eine leere Zeichenfolge.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

Weitere Informationen finden Sie unter Kontexte und unter Verwenden von Geheimnissen in GitHub-Aktionen.

jobs.<job_id>.steps[*].name

Name deines Schritts, der auf GitHub angezeigt wird.

jobs.<job_id>.steps[*].uses

Wählt eine Aktion aus, die als Teil eines Schritts im Job ausgeführt wird. Eine Aktion ist eine wiederverwendbare Code-Einheit. Du kannst eine Aktion verwenden, die im selben Repository wie der Workflow, in einem öffentlichen Repository oder in einem veröffentlichten Docker-Containerimage definiert ist.

Es wird dringend empfohlen, dass du die Version der verwendeten Aktion einschließt, indem du Git-ref, SHA oder ein Docker-Tag angibst. Wenn du keine Version angibst, könnten damit die Workflows gestört werden, oder es wird ein unerwartetes Verhalten hervorgerufen, wenn der bzw. die Besitzer*in der Aktion eine Aktualisierung veröffentlicht.

  • Am besten in Hinblick auf Stabilität und Sicherheit ist es, die Commit-SHA einer freigegebenen Version einer Aktion zu verwenden.
  • Wenn die Aktion Hauptversionstags veröffentlicht, kannst du kritische Fehlerbehebungen und Sicherheitspatches erhalten und gleichzeitig die Kompatibilität wahren. Hinweis: Dieses Verhalten liegt im Ermessen des Autors der Aktion.
  • Die Verwendung des Standardbranches einer Aktion ist zwar auf den ersten Blick praktisch, doch wenn eine neue Hauptversion mit einem Breaking Change veröffentlicht wird, könnte der Workflow unterbrochen werden.

Einige Aktionen erfordern Eingaben, die du mit dem Schlüsselwort with festlegen musst. Die erforderlichen Eingaben findest du in der README-Datei der Aktion.

Aktionen sind entweder JavaScript-Dateien oder Docker-Container. Bei Docker-Containern als Aktion musst du den Auftrag in einer Linux-Umgebung ausführen. Weitere Informationen findest du unter runs-on.

Beispiel: Verwenden versionierter Aktionen

steps:
  # Reference a specific commit
  - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
  # Reference the major version of a release
  - uses: actions/checkout@v4
  # Reference a specific version
  - uses: actions/checkout@v4.2.0
  # Reference a branch
  - uses: actions/checkout@main

Beispiel: Verwenden einer öffentlichen Aktion

{owner}/{repo}@{ref}

Du kannst einen Branch, einen Verweis oder einen SHA-Wert in einem öffentlichen GitHub-Repository angeben.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

Beispiel: Verwenden einer öffentlichen Aktion in einem Unterverzeichnis

{owner}/{repo}/{path}@{ref}

Ein Unterverzeichnis in einem öffentlichen Repository auf GitHub in einem bestimmten Branch, einer bestimmten Ref oder einer bestimmten SHA.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

Beispiel: Verwenden einer Aktion im selben Repository wie der Workflow

./path/to/dir

Der Pfad zum Verzeichnis, das die Aktion im Repository deines Workflows enthält. Du musst dein Repository auschecken, bevor du die Aktion verwendest.

Example repository file structure:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

The path is relative (./) to the default working directory (github.workspace, $GITHUB_WORKSPACE). If the action checks out the repository to a location different than the workflow, the relative path used for local actions must be updated.

Example workflow file:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

Beispiel: Verwenden einer Docker Hub-Aktion

docker://{image}:{tag}

Dies ist ein Docker-Image, das in Docker Hub veröffentlicht wurde.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Beispiel: Verwenden der GitHub Packages-Container registry

docker://{host}/{image}:{tag}

Dies ist ein öffentliches Docker-Image in der GitHub Packages-Container registry.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://ghcr.io/OWNER/IMAGE_NAME

Beispiel: Verwenden einer Aktion in einer öffentlichen Docker-Registrierung

docker://{host}/{image}:{tag}

Ein Docker-Image in einer öffentlichen Registry. Dieses Beispiel verwendet die Google Container Registry unter gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

Beispiel: Verwenden einer Aktion innerhalb eines anderen privaten Repositorys als dem Workflow

Dein Workflow muss das private Repository auschecken und lokal auf die Aktion verweisen. Generiere ein personal access token, und füge das Token als Geheimnis hinzu. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken und unter Verwenden von Geheimnissen in GitHub-Aktionen.

Ersetze PERSONAL_ACCESS_TOKEN im Beispiel durch den Namen deines Geheimnisses.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

Alternativ kannst du eine GitHub App anstelle eines personal access token verwenden, um sicherzustellen, dass dein Workflow auch dann ausgeführt wird, wenn derdie personal access token-Besitzerin nicht mehr da ist. Weitere Informationen findest du unter Authentifizierte API-Anforderungen mit einer GitHub-App in einem GitHub Actions-Workflow.

jobs.<job_id>.steps[*].run

Führt Befehlszeilenprogramme aus, die nicht mehr als 21 000 Zeichen umfassen, und verwendet dabei die Shell des Betriebssystems. Wenn du keinen name angibst, wird standardmäßig der im run-Befehl angegebene Text als Schrittname verwendet.

Befehle greifen standardmäßig auf Shells zurück, für die keine Anmeldung erforderlich ist. Du kannst für die Ausführung von Befehlen eine andere Shell auswählen und die Shell anpassen. Weitere Informationen findest du unter jobs.<job_id>.steps[*].shell.

Jedes run-Schlüsselwort stellt einen neuen Prozess und eine neue Shell in der Runnerumgebung dar. Wenn du mehrzeilige Befehle angibst, werden alle Zeilen in derselben Shell ausgeführt. Beispiel:

  • Einzeiliger Befehl:

    - name: Install Dependencies
      run: npm install
    
  • Mehrzeiliger Befehl:

    - name: Clean install dependencies and build
      run: |
        npm ci
        npm run build
    

jobs.<job_id>.steps[*].working-directory

Mithilfe des working-directory-Schlüsselworts kannst du das Arbeitsverzeichnis angeben, in dem der Befehl ausgeführt werden soll.

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

Alternativ können Sie ein Standard-Arbeitsverzeichnis für alle run Schritte in einem Auftrag oder für alle run Schritte im gesamten Workflow angeben. Weitere Informationen finden Sie unter „defaults.run“ und „jobs.<job_id>.defaults.run“.

Sie können auch einen run-Schritt zum Ausführen eines Skripts verwenden. Weitere Informationen findest du unter Grundlegende Features von GitHub Actions.

jobs.<job_id>.steps[*].shell

Du kannst die Standardshelleinstellungen im Betriebssystem des Runners mithilfe des Schlüsselworts shell überschreiben. Du hast die Möglichkeit, integrierte shell-Schlüsselworte zu verwenden oder eine benutzerdefinierte Shelloptionen zu definieren. Der intern ausgeführte Shellbefehl führt eine temporäre Datei aus, die die im Schlüsselwort run angegebenen Befehle enthält.

Unterstützte Plattformshell-ParameterBESCHREIBUNGIntern ausgeführter Befehl
Linux/macOSunspecifiedDie Standardshell auf Nicht-Windows-Plattformen. Beachte, dass dadurch ein anderer Befehl ausgeführt wird, wenn bash explizit angegeben wird. Wenn bash nicht im Pfad gefunden wird, wird es als sh behandelt.bash -e {0}
AllebashDies ist die Standardshell auf Nicht-Windows-Plattformen mit einem Fallback zu sh. Wenn eine Bash-Shell für Windows angegeben wird, wird die in Git für Windows enthaltene Bash-Shell verwendet.bash --noprofile --norc -eo pipefail {0}
AllpwshDer PowerShell Core. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an.pwsh -command ". '{0}'"
AllepythonFührt den Befehl Python aus.python {0}
Linux/macOSshDies ist das Fallbackverhalten für Nicht-Windows-Plattformen, falls keine Shell bereitgestellt ist und bash nicht im Pfad gefunden wird.sh -e {0}
WindowscmdGitHub fügt die Erweiterung .cmd an deinen Skriptnamen an und ersetzt {0}.%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshDies ist die standardmäßig für Windows verwendete Shell. Der PowerShell Core. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. Wenn in deinem selbstgehosteten Windows-Runner PowerShell Core nicht installiert ist, wird stattdessen PowerShell Desktop verwendet.pwsh -command ". '{0}'".
WindowspowershellPowerShell Desktop. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an.powershell -command ". '{0}'".

Beispiel: Ausführen eines Befehls mit Bash

steps:
  - name: Display the path
    shell: bash
    run: echo $PATH

Beispiel: Ausführen eines Befehls unter Windows cmd

steps:
  - name: Display the path
    shell: cmd
    run: echo %PATH%

Beispiel: Ausführen eines Befehls mit PowerShell Core

steps:
  - name: Display the path
    shell: pwsh
    run: echo ${env:PATH}

Beispiel: Verwenden von PowerShell Desktop zum Ausführen eines Befehls

steps:
  - name: Display the path
    shell: powershell
    run: echo ${env:PATH}

Beispiel: Ausführen eines Inline-Python-Skripts

steps:
  - name: Display the path
    shell: python
    run: |
      import os
      print(os.environ['PATH'])

Benutzerdefinierte Shell

Du kannst den shell-Wert mithilfe von command [options] {0} [more_options] auf eine Vorlagenzeichenfolge festlegen. GitHub interpretiert das erste durch ein Leerzeichen getrennte Wort in der Zeichenfolge als den Befehl und fügt den Dateinamen für das temporäre Skript bei {0} ein.

Beispiel:

steps:
  - name: Display the environment variables and their values
    shell: perl {0}
    run: |
      print %ENV

Der in diesem Beispiel verwendete Befehl perl muss im Runner installiert werden.

Informationen zu der Software, die auf GitHub gehosteten Runnern enthalten ist, finden Sie unter „Verwenden von auf GitHub gehosteten Runnern.“

Exit-Codes und Voreinstellung für Fehleraktionen

Für integrierte Shell-Schlüsselwörter gelten die folgenden Standards, die durch auf GitHub gehostete Runner ausgeführt werden. Beachte diese Richtlinien beim Ausführen von Shell-Skripts.

  • bash/sh:

    • Standardmäßig wird das Fail-Fast-Verhalten mit set -e sowohl für sh als auch bash durchgesetzt. Wenn shell: bash angegeben ist, wird -o pipefail ebenfalls angewendet, um die vorzeitige Beendigungen von Pipelines zu erzwingen, die einen anderen Beendigungsstatus als null generieren.
    • Du kannst die volle Kontrolle über Shellparameter übernehmen, indem du einen Vorlagenstring für die Shelloptionen bereitstellst. Beispielsweise bash {0}.
    • sh-ähnliche Shells werden mit dem Exitcode des letzten Befehls beendet, der im Skript ausgeführt wurde. Dies ist auch das Standardverhalten für Aktionen. Der Runner meldet den Status des Schritts gemäß diesem Exitcodeode als Fehler/Erfolg.
  • powershell/pwsh

    • Fail-Fast-Verhalten, soweit möglich. Bei den integrierten Shells pwsh und powershell wird den Skriptinhalten $ErrorActionPreference = 'stop' vorangestellt.
    • PowerShell-Skripts wird if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } angefügt, damit Aktionsstatus den letzten Exitcode des Skripts widerspiegeln.
    • Benutzer*innen haben immer die Möglichkeit, die integrierte Shell nicht zu verwenden und stattdessen eine benutzerdefinierte Shelloption wie pwsh -File {0} oder powershell -Command "& '{0}'" (je nach Bedarf) bereitzustellen.
  • cmd

    • Wenn du das Fail-Fast-Verhalten uneingeschränkt nutzen möchtest, hast du anscheinend keine andere Wahl, als dein Skript so zu schreiben, dass jeder Fehlercode geprüft und eine entsprechende Reaktion eingeleitet wird. Dieses Verhalten kann nicht standardmäßig bereitgestellt werden. Du musst es explizit in dein Skript schreiben.
    • cmd.exe wird mit der Fehlerstufe des zuletzt ausgeführten Programms beendet, und dieser Fehlercode wird an den Runner zurückgegeben. Dieses Verhalten ist intern mit dem vorherigen sh- und pwsh-Standardverhalten konsistent und entspricht dem cmd.exe-Standard, sodass dieses Verhalten intakt bleibt.

jobs.<job_id>.steps[*].with

Dies ist eine map der Eingabeparameter, die durch die Aktion definiert werden. Jeder Eingabeparameter ist ein Schlüssel-Wert-Paar. Eingabeparameter werden als Umgebungsvariablen festgelegt. Die Variable wird mit dem Präfix INPUT_ versehen und in Großbuchstaben konvertiert.

Eingabeparameter, die für einen Docker-Container definiert sind, müssen args verwenden. Weitere Informationen findest du unter jobs.<job_id>.steps[*].with.args.

Beispiel für jobs.<job_id>.steps[*].with

Die drei Eingabeparameter (first_name, middle_name und last_name) werden durch die hello_world-Aktion definiert. Diese Eingabevariablen sind für die hello-world-Aktion über die Umgebungsvariablen INPUT_FIRST_NAME, INPUT_MIDDLE_NAME und INPUT_LAST_NAME zugänglich.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Dies ist ein string, der die Eingaben für einen Docker-Container definiert. GitHub übergibt args beim Start des Containers an dessen ENTRYPOINT. Ein array of strings wird von diesem Parameter nicht unterstützt. Ein einzelnes Argument, das Leerzeichen enthält, sollte in doppelte Anführungszeichen "" eingeschlossen werden.

Beispiel für jobs.<job_id>.steps[*].with.args

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

Die args-Elemente werden anstelle der CMD-Anweisung in Dockerfile verwendet. Wenn du CMD in Dockerfile verwendest, befolge diese Hinweise (nach Präferenz sortiert):

  1. Dokumentiere die erforderlichen Argumente in der README-Datei der Aktion, und lasse sie in der CMD-Anweisung weg.
  2. Verwende Standardwerte, die die Verwendung der Aktion ohne die Angabe von args ermöglichen.
  3. Wenn die Aktion ein --help-Flag oder etwas ähnliches verfügbar macht, verwende dies als Standard, damit die Aktion selbstdokumentierend wird.

jobs.<job_id>.steps[*].with.entrypoint

Hiermit wird ENTRYPOINT für Docker in Dockerfile überschrieben oder ein Einstiegspunkt festgelegt, falls noch keiner vorhanden ist. Im Gegensatz zur Docker-Anweisung ENTRYPOINT mit einer Shell und einem Ausführungsformat, akzeptiert das Schlüsselwort entrypoint nur eine einzelne Zeichenfolge, die die ausführbare Datei definiert, die ausgeführt werden soll.

Beispiel für jobs.<job_id>.steps[*].with.entrypoint

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

Das Schlüsselwort entrypoint ist für die Verwendung mit Docker-Containeraktionen vorgesehen, du kannst es jedoch auch mit JavaScript-Aktionen verwenden, die keine Eingaben definieren.

jobs.<job_id>.steps[*].env

Damit werden Variablen für Schritte festgelegt, die in der Runner-Umgebung verwendet werden sollen. Darüber hinaus kannst du Variablen für den gesamten Workflow oder für einen Auftrag festlegen. Weitere Informationen findest du unter env und jobs.<job_id>.env.

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.

Die erwarteten Variablen können durch öffentliche Aktionen in der Infodatei angegeben werden. Wenn du einen geheimen oder vertraulichen Wert festlegst, z. B. ein Kennwort oder ein Token, musst du Geheimnisse mithilfe des Kontexts secrets festlegen. Weitere Informationen findest du unter Kontexte.

Beispiel für jobs.<job_id>.steps[*].env

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Verhindert das Fehlschlagen eines Auftrags, wenn ein Schritt fehlschlägt. Lege dies auf true fest, damit ein Auftrag erfolgreich abgeschlossen werden kann, wenn bei diesem Schritt ein Fehler auftritt.

jobs.<job_id>.steps[*].timeout-minutes

Maximaler Zeitraum in Minuten für die Ausführung des Schritts, bevor der Prozess abgebrochen wird.

jobs.<job_id>.timeout-minutes

Die maximale Anzahl von Minuten, die ein Job ausgeführt wird, bevor GitHub automatisch abbricht. Standard: 360

Sollte das Timeout das Zeitlimit für die Auftragsausführung für den Runner überschreitet, wird der Auftrag abgebrochen, wenn stattdessen das Zeitlimit für die Ausführung erreicht wird. Weitere Informationen zu Zeitlimits bei der Auftragsausführung finden Sie unter Nutzungseinschränkungen, Abrechnung und Verwaltung für auf GitHub gehostete Runner und unter Informationen zu selbstgehosteten Runnern für Nutzungseinschränkungen für selbstgehostete Runner.

Hinweis: GITHUB_TOKEN läuft ab, wenn ein Auftrag beendet wird bzw. spätestens nach 24 Stunden. Für selbstgehostete Runner kann das Token der begrenzende Faktor sein, wenn das Auftragstimeout mehr als 24 Stunden beträgt. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung.

jobs.<job_id>.strategy

Mithilfe von jobs.<job_id>.strategy kannst du eine Matrixstrategie für deine Aufträge verwenden. Mithilfe einer Matrixstrategie kannst du Variablen in einer Auftragsdefinition verwenden, um automatisch mehrere Auftragsausführungen zu erstellen, die auf Kombinationen dieser Variablen basieren. Mithilfe einer Matrixstrategie kannst du deinen Code beispielsweise in mehreren Versionen einer Sprache oder auf mehreren Betriebssystemen testen. Weitere Informationen findest du unter Verwenden von Matrizen für deine Aufträge.

jobs.<job_id>.strategy.matrix

Verwende jobs.<job_id>.strategy.matrix, um eine Matrix verschiedener Auftragskonfigurationen zu definieren. Definiere innerhalb der Matrix eine oder mehrere Variablen, gefolgt von einem Array an Werten. Die folgende Matrix verfügt beispielsweise über eine Variable namens version mit dem Wert [10, 12, 14] und über eine Variable namens os mit dem Wert [ubuntu-latest, windows-latest]:

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

Für jede mögliche Kombination der Variablen wird ein Auftrag ausgeführt. In diesem Beispiel führt der Workflow sechs Aufträge aus: einen für jede Kombination der Variablen os und version.

Standardmäßig maximiert GitHub Enterprise Cloud die Anzahl der parallel ausgeführten Aufträge basierend auf der Runnerverfügbarkeit. Die Reihenfolge der Variablen in der Matrix bestimmt die Reihenfolge, in der die Aufträge erstellt werden. Die erste Variable, die du definierst, entspricht dem ersten Auftrag, der in deiner Workflowausführung erstellt wird. Die Matrix oben erstellt die Aufträge beispielsweise in der folgenden Reihenfolge:

  • {version: 10, os: ubuntu-latest}
  • {version: 10, os: windows-latest}
  • {version: 12, os: ubuntu-latest}
  • {version: 12, os: windows-latest}
  • {version: 14, os: ubuntu-latest}
  • {version: 14, os: windows-latest}

Eine Matrix generiert maximal 256 Aufträge pro Workflowausführung. Dieser Grenzwert gilt sowohl für von GitHub Enterprise Cloud gehostete als auch selbstgehostete Runner.

Die von dir definierten Variablen werden zu Eigenschaften im matrix-Kontext, und du kannst in anderen Bereichen deiner Workflowdatei auf die Eigenschaft verweisen. In diesem Beispiel kannst du matrix.version und matrix.os verwenden, um auf die aktuellen Werte von version und os zuzugreifen, die der Auftrag nutzt. Weitere Informationen findest du unter Kontexte.

Beispiel: Verwenden einer Matrix mit einer einzelnen Dimension

Du kannst eine einzelne Variable angeben, um eine Matrix mit einer einzelnen Dimension zu erstellen.

Der folgende Workflow definiert beispielsweise die Variable version mit den Werten [10, 12, 14]. Dieser Workflow führt drei Aufträge aus, einen für jeden Wert in der Variablen. Jeder Auftrag greift über den matrix.version-Kontext auf den version-Wert zu und übergibt den Wert als node-version an die actions/setup-node-Aktion.

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Beispiel: Verwenden einer Matrix mit mehreren Dimensionen

Du kannst mehrere Variablen angeben, um eine mehrdimensionale Matrix zu erstellen. Für jede mögliche Kombination der Variablen wird ein Auftrag ausgeführt.

Der folgende Workflow gibt beispielsweise zwei Variablen an:

  • Zwei Betriebssysteme, die in der Variable os angegeben sind
  • Drei Node.js-Versionen, die in der Variable version angegeben sind

Der Workflow führt sechs Aufträge aus, einen für jede Kombination der Variablen os und version. Jeder Auftrag legt den Wert runs-on auf den aktuellen Wert os fest und übergibt den aktuellen Wert version an die Aktion actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Beispiel: Erstellen von Matrizen mithilfe von Kontexten

Du kannst Kontexte verwenden, um Matrizen zu erstellen. Weitere Informationen zu Kontexten findest du unter Kontexte.

Beispielsweise wird der folgende Workflow für das repository_dispatch-Ereignis ausgelöst und verwendet Informationen aus der Ereignisnutzlast, um die Matrix zu erstellen. Wenn ein Repositorydispatchereignis mit einer Nutzlast wie der folgenden erstellt wird, hat die Matrixvariable version einen Wert von [12, 14, 16]. Weitere Informationen zum Trigger repository_dispatch findest du unter Ereignisse zum Auslösen von Workflows.

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}
on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

Verwende jobs.<job_id>.strategy.matrix.include, um vorhandene Matrixkonfigurationen zu erweitern oder neue Konfigurationen hinzuzufügen. Der Wert von include ist eine Liste von Objekten.

Die Schlüssel-Wert-Paare im Objekt werden für jedes Objekt in der include-Liste zu jeder der Matrixkombinationen hinzugefügt, wenn keines der Schlüssel-Wert-Paare einen der ursprünglichen Matrixwerte überschreibt. Wenn das Objekt zu keiner der Matrixkombinationen hinzugefügt werden kann, wird stattdessen eine neue Matrixkombination erstellt. Beachte, dass die ursprünglichen Matrixwerte nicht überschrieben werden, hinzugefügte Matrixwerte jedoch überschrieben werden können.

Diese Matrix ergibt sechs Aufträge mit den folgenden Matrixkombinationen:

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

führt zu sechs Aufträgen mit den folgenden Matrixkombinationen:

  • {fruit: apple, animal: cat, color: pink, shape: circle}
  • {fruit: apple, animal: dog, color: green, shape: circle}
  • {fruit: pear, animal: cat, color: pink}
  • {fruit: pear, animal: dog, color: green}
  • {fruit: banana}
  • {fruit: banana, animal: cat}

Sie befolgen diese Logik:

  • {color: green} wird allen ursprünglichen Matrixkombinationen hinzugefügt, da sie hinzugefügt werden kann, ohne einen Teil der ursprünglichen Kombinationen zu überschreiben.
  • {color: pink, animal: cat} fügt color:pink nur den ursprünglichen Matrixkombinationen hinzu, die animal: cat enthalten. Dadurch wird die color: green überschrieben, die zuvor durch den vorherigen include-Eintrag hinzugefügt wurde.
  • {fruit: apple, shape: circle} fügt shape: circle nur den ursprünglichen Matrixkombinationen hinzu, die fruit: apple enthalten.
  • {fruit: banana} kann zu keiner ursprünglichen Matrixkombination hinzugefügt werden, ohne dass dabei ein Wert überschrieben wird. Daher wird sie als zusätzliche Matrixkombination hinzugefügt.
  • {fruit: banana, animal: cat} kann zu keiner ursprünglichen Matrixkombination hinzugefügt werden, ohne dass dabei ein Wert überschrieben wird. Daher wird sie als zusätzliche Matrixkombination hinzugefügt. Die {fruit: banana}-Matrixkombination wird nicht hinzugefügt, da die Kombination keine der ursprünglichen Matrixkombinationen war.

Beispiel: Erweitern von Konfigurationen

Beispielsweise führt der folgende Workflow vier Jobs aus, einen für jede Kombination von os und node. Wenn der Auftrag für den os-Wert von windows-latest und den node-Wert von 16 ausgeführt wird, wird eine zusätzliche Variable namens npm mit dem Wert 6 in den Auftrag einbezogen.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Beispiel: Hinzufügen von Konfigurationen

Diese Matrix führt beispielsweise zehn Aufträge aus, einen für jede Kombination von os und version in der Matrix sowie einen Auftrag für den Wert os von windows-latest und den Wert version von 17.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

Wenn du keine Matrixvariablen angibst, werden alle Konfigurationen unter include ausgeführt. Der folgende Workflow würde beispielsweise zwei Aufträge ausführen, einen für jeden include-Eintrag. Auf diese Weise kannst du die Matrixstrategie nutzen, ohne eine vollständig ausgefüllte Matrix zu haben.

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

Um bestimmte Konfigurationen zu entfernen, die in der Matrix definiert sind, verwende jobs.<job_id>.strategy.matrix.exclude. Eine ausgeschlossene Konfiguration muss nur eine teilweise Übereinstimmung sein, damit sie ausgeschlossen werden kann. Der folgende Workflow führt z. B. neun Aufträge aus: ein Auftrag für jede der 12 Konfigurationen, minus der ausgeschlossenen Aufgabe, die mit {os: macos-latest, version: 12, environment: production} übereinstimmt, und die beiden ausgeschlossenen Aufträge, die mit {os: windows-latest, version: 16} übereinstimmen.

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

Hinweis: Alle include-Kombinationen werden nach exclude verarbeitet. So kannst du mit include wieder Kombinationen hinzufügen, die zuvor ausgeschlossen waren.

jobs.<job_id>.strategy.fail-fast

Du kannst steuern, wie Auftragsfehler mit jobs.<job_id>.strategy.fail-fast und jobs.<job_id>.continue-on-error verarbeitet werden.

jobs.<job_id>.strategy.fail-fast gilt für die gesamte Matrix. Wenn jobs.<job_id>.strategy.fail-fast auf true festgelegt ist oder sein Ausdruck den Wert true annimmt, bricht GitHub Enterprise Cloud alle in Verarbeitung oder in der Warteschlange befindlichen Aufträge in der Matrix ab, wenn bei einem Auftrag in der Matrix ein Fehler auftritt. Der Standardwert dieser Eigenschaft ist true.

jobs.<job_id>.continue-on-error gilt für einen einzelnen Auftrag. Wenn jobs.<job_id>.continue-on-error auf true festgelegt ist, werden andere Aufträge in der Matrix weiterhin ausgeführt, auch wenn bei dem Auftrag mit jobs.<job_id>.continue-on-error: true ein Fehler auftritt.

Du kannst jobs.<job_id>.strategy.fail-fast und jobs.<job_id>.continue-on-error gemeinsam einsetzen. Der folgende Workflow startet beispielsweise vier Aufträge. Für jeden Auftrag wird continue-on-error durch den Wert von matrix.experimental bestimmt. Wenn bei einem der Aufträge mit continue-on-error: false ein Fehler auftritt, werden alle in Verarbeitung oder in der Warteschlange befindlichen Aufträge abgebrochen. Wenn beim Auftrag mit continue-on-error: true ein Fehler auftritt, sind die anderen Aufträge nicht betroffen.

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

Standardmäßig maximiert GitHub Enterprise Cloud die Anzahl der parallel ausgeführten Aufträge basierend auf der Runnerverfügbarkeit. Um die maximale Anzahl von Aufträgen festzulegen, die bei der Auftragsstrategie matrix gleichzeitig ausgeführt werden können, verwende jobs.<job_id>.strategy.max-parallel.

Der folgende Workflow führt zum Beispiel maximal zwei Aufträge auf einmal aus, auch wenn es Runner gibt, die alle sechs Aufträge auf einmal ausführen können.

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

Verhindert, dass ein Workflow scheitert, wenn ein Job scheitert. Lege dies auf true fest, damit eine Workflowausführung erfolgreich abgeschlossen werden kann, wenn bei diesem Auftrag ein Fehler auftritt.

Beispiel: Verhindern, dass ein bestimmter fehlgeschlagener Matrixauftrag zu einem Fehler bei einer Workflowausführung führt

Du kannst zulassen, dass bestimmte Jobs in einer Jobmatrix scheitert, ohne dass der Workflow-Lauf scheitert. Dies gilt beispielsweise, wenn du festlegen möchtest, dass nur bei einem experimentellen Auftrag, für den node auf 15 festgelegt ist, ein Fehler auftreten darf, ohne dass dadurch ein Fehler bei der Workflowausführung auftritt.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        experimental: true

jobs.<job_id>.container

Hinweis: Wenn deine Workflows Docker-Containeraktionen, Auftragscontainer oder Dienstcontainer verwenden, musst du einen Linux-Runner verwenden:

  • Wenn du GitHub-gehostete Runner verwendest, musst du einen Ubuntu-Runner verwenden.
  • Wenn du selbst gehostete Läufer verwendest, musst du einen Linux-Rechner als deinen Läufer verwenden und Docker muss installiert sein.

Verwende jobs.<job_id>.container, um einen Container zu erstellen, in dem alle Schritte eines Jobs ausgeführt werden, die noch keinen Container angeben. Wenn ein Schritt sowohl Skript- als auch Container-Aktionen umfasst, werden die Container-Aktionen als nebengeordnete Container in demselben Netzwerk mit denselben Volume-Mounts ausgeführt.

Wenn du keinen container festlegst, werden alle Schritte direkt auf dem durch runs-on angegebenen Host ausgeführt, es sei denn, ein Schritt bezieht sich auf eine Aktion, die für die Ausführung in einem Container konfiguriert ist.

Hinweis: Die Standardshell für run-Schritte innerhalb eines Containers lautet sh anstelle von bash. Dies kann mit jobs.<job_id>.defaults.run oder jobs.<job_id>.steps[*].shell überschrieben werden.

Beispiel: Ausführen eines Auftrags innerhalb eines Containers

YAML
name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

Wenn du nur ein Containerimage angibst, kannst du das image-Schlüsselwort weglassen.

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:18

jobs.<job_id>.container.image

Verwende jobs.<job_id>.container.image, um das Docker-Image zu definieren, das beim Ausführen der Aktion als Container herangezogen wird. Der Wert kann der Name des Docker Hub-Images oder ein Registrierungsname sein.

jobs.<job_id>.container.credentials

Wenn die Containerregistrierung des Images eine Authentifizierung benötigt, damit das Image gepullt werden kann, kannst du mit jobs.<job_id>.container.credentials eine map von username und password festlegen. Die Anmeldeinformationen sind dieselben Werte, die du für den docker login-Befehl angeben würdest.

Beispiel: Definieren der Anmeldeinformationen für eine Containerregistrierung

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

Verwende jobs.<job_id>.container.env, um eine map von Umgebungsvariablen im Dienstcontainer einzustellen.

jobs.<job_id>.container.ports

Verwende jobs.<job_id>.container.ports zum Festlegen eines array aus Ports, die für den Container verfügbar gemacht werden sollen.

jobs.<job_id>.container.volumes

Verwende jobs.<job_id>.container.volumes zum Festlegen eines array von Volumes, die der Container verwenden soll. Mithilfe von Volumes kannst Du Daten zwischen Diensten oder anderen Schritten in einem Job austauschen. Du kannst benannte Docker-Volumes, anonyme Docker-Volumes oder Bind-Mounts auf dem Host angegeben.

Um ein Volume festzulegen, gibst du den Quell- und Zielpfad an:

<source>:<destinationPath>.

<source> ist ein Volumename oder ein absoluter Pfad auf dem Hostcomputer, und <destinationPath> ist ein absoluter Pfad im Container.

Beispiel: Einbinden von Volumes in einem Container

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

Verwende jobs.<job_id>.container.options zum Konfigurieren zusätzlicher Optionen für Docker-Containerressourcen. Eine Liste der Optionen findest du unter docker create-Optionen.

Warnung: Die Optionen --network und --entrypoint werden nicht unterstützt.

jobs.<job_id>.services

Hinweis: Wenn deine Workflows Docker-Containeraktionen, Auftragscontainer oder Dienstcontainer verwenden, musst du einen Linux-Runner verwenden:

  • Wenn du GitHub-gehostete Runner verwendest, musst du einen Ubuntu-Runner verwenden.
  • Wenn du selbst gehostete Läufer verwendest, musst du einen Linux-Rechner als deinen Läufer verwenden und Docker muss installiert sein.

Wird zum Betrieb von Servicecontainern für einen Job in einem Workflow verwendet. Servicecontainer sind nützlich, um Datenbanken oder Cache-Dienste wie Redis zu erstellen. Der Runner erstellt automatisch ein Docker-Netzwerk und verwaltet den Lebenszyklus der Service-Container.

Wenn du deinen Auftrag so konfigurierst, dass er in einem Container ausgeführt wird, oder wenn dein Schritt Containeraktionen verwendet, brauchst du keine Ports zuzuordnen, um auf den Dienst oder die Aktion zuzugreifen. Docker öffnet automatisch alle Ports zwischen Containern im selben benutzerdefinierten Bridge-Netzwerk des Dockers. Du kannst den Servicecontainer direkt mit seinem Hostnamen referenzieren. Der Hostname wird automatisch dem Namen der Bezeichnung zugeordnet, die du für den Dienst im Workflow konfigurierst.

Wenn du den Auftrag so konfigurierst, dass er direkt auf dem Runnercomputer ausgeführt wird und dein Schritt keine Containeraktion verwendet, musst du alle erforderlichen Ports des Docker-Servicecontainers dem Docker-Host (dem Runnercomputer) zuordnen. Du kannst auf den Servicecontainer über localhost und den zugeordneten Port zugreifen.

Weitere Informationen zu den Unterschieden zwischen Netzwerkdienstcontainern findest du unter Informationen zu Service-Containern.

Beispiel: Verwenden des Localhosts

Dieses Beispiel erzeugt zwei Dienste: nginx und redis. Wenn Du den Port des Docker-Hosts angibst, aber nicht den des Containers, dann wird der Container-Port zufällig einem freien Port zugewiesen. GitHub legt den zugewiesenen Containerport im ${{job.services.<service_name>.ports}}-Kontext fest. In diesem Beispiel kannst du mithilfe der Kontexte ${{ job.services.nginx.ports['8080'] }} und ${{ job.services.redis.ports['6379'] }} auf die Dienstcontainerports zugreifen.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

Docker-Image, das beim Ausführen der Aktion als Dienstcontainer herangezogen wird. Der Wert kann der Name des Docker Hub-Images oder ein Registrierungsname sein.

jobs.<job_id>.services.<service_id>.credentials

Wenn die Containerregistrierung des Images eine Authentifizierung benötigt, damit das Image gepullt werden kann, kannst du mit jobs.<job_id>.container.credentials eine map von username und password festlegen. Die Anmeldeinformationen sind dieselben Werte, die du für den docker login-Befehl angeben würdest.

Beispiel für jobs.<job_id>.services.<service_id>.credentials

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

Hiermit wird eine map von Umgebungsvariablen im Dienstcontainer festgelegt.

jobs.<job_id>.services.<service_id>.ports

Hiermit wird ein array von Ports festgelegt, die auf dem Dienstcontainer verfügbar gemacht werden sollen.

jobs.<job_id>.services.<service_id>.volumes

Hiermit wird ein array von Volumes festgelegt, die der Dienstcontainer verwenden soll. Mithilfe von Volumes kannst Du Daten zwischen Diensten oder anderen Schritten in einem Job austauschen. Du kannst benannte Docker-Volumes, anonyme Docker-Volumes oder Bind-Mounts auf dem Host angegeben.

Um ein Volume festzulegen, gibst du den Quell- und Zielpfad an:

<source>:<destinationPath>.

<source> ist ein Volumename oder ein absoluter Pfad auf dem Hostcomputer, und <destinationPath> ist ein absoluter Pfad im Container.

Beispiel für jobs.<job_id>.services.<service_id>.volumes

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Zusätzliche Optionen für die Docker-Container-Ressource. Eine Liste der Optionen findest du unter docker create-Optionen.

Warnung: Die --network-Option wird nicht unterstützt.

jobs.<job_id>.uses

Dies ist der Speicherort und die Version einer wiederverwendbaren Workflowdatei, die als Auftrag ausgeführt werden soll. Verwende eine 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.

Beispiel für jobs.<job_id>.uses

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

Weitere Informationen findest du unter Wiederverwenden von Workflows.

jobs.<job_id>.with

Wenn ein Auftrag zum Aufrufen eines wiederverwendbaren Workflows verwendet wird, kannst du mit with eine Zuordnung von Eingaben bereitstellen, die an den aufgerufenen Workflow übergeben werden.

Alle Eingaben, die du übergibst, müssen den im aufgerufenen Workflow definierten Eingabespezifikationen entsprechen.

Im Gegensatz zu jobs.<job_id>.steps[*].with sind die mit jobs.<job_id>.with übergebenen Eingaben nicht als Umgebungsvariablen im aufgerufenen Workflow verfügbar. Stattdessen kannst du mithilfe des inputs-Kontexts auf die Eingaben verweisen.

Beispiel für jobs.<job_id>.with

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

Dies ist ein aus einem Zeichenfolgenbezeichner für die Eingabe und dem Wert für die Eingabe bestehendes Paar. Der Bezeichner muss mit dem Namen der Eingabe übereinstimmen, die von on.workflow_call.inputs.<inputs_id> im aufgerufenen Workflow definiert wird. Der Datentyp des Werts muss mit dem Typ übereinstimmen, der von on.workflow_call.inputs.<input_id>.type im aufgerufenen Workflow definiert wird.

Zulässiger Ausdruckskontext: github und needs.

jobs.<job_id>.secrets

Wenn ein Auftrag zum Aufrufen eines wiederverwendbaren Workflows verwendet wird, kannst du mit secrets eine Zuordnung von Geheimnissen bereitstellen, die an den aufgerufenen Workflow übergeben werden.

Alle Geheimnisse, die du übergibst, müssen mit den Namen übereinstimmen, die im aufgerufenen Workflow definiert sind.

Beispiel für jobs.<job_id>.secrets

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.inherit

Verwende das Schlüsselwort inherit, um alle Geheimnisse des aufrufenden Workflows an den aufgerufenen Workflow zu übergeben. Dazu gehören alle Geheimnisse, auf die der aufrufende Workflow Zugriff hat, nämlich die Geheimnisse von Organisation, Repository und Umgebung. Das Schlüsselwort inherit kann verwendet werden, um Geheimnisse zwischen Repositorys innerhalb derselben Organisation oder zwischen Organisationen innerhalb desselben Unternehmens zu übergeben.

Beispiel für jobs.<job_id>.secrets.inherit

on:
  workflow_dispatch:

jobs:
  pass-secrets-to-workflow:
    uses: ./.github/workflows/called-workflow.yml
    secrets: inherit
on:
  workflow_call:

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
      - name: Use a repo or org secret from the calling workflow.
        run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}

jobs.<job_id>.secrets.<secret_id>

Dies ist ein aus einem Zeichenfolgenbezeichner für das Geheimnis und dem Wert für das Geheimnis bestehendes Paar. Der Bezeichner muss mit dem Namen eines Geheimnisses übereinstimmen, das von on.workflow_call.secrets.<secret_id> im aufgerufenen Workflow definiert wird.

Zulässiger Ausdruckskontext: github, needs und secrets.

Spickzettel für Filtermuster

In Pfad-, Branch- und Tagfiltern kannst du Sonderzeichen benutzen.

  • *: Gleicht null oder mehr Zeichen ab, nicht jedoch das /-Zeichen. Beispielsweise entspricht Octo*``Octocat.
  • **: Gleicht null oder mehr beliebige Zeichen ab.
  • ?: Gleicht null oder eines der vorherigen Zeichen ab.
  • +: Gleicht eines oder mehrere der vorherigen Zeichen ab.
  • []: Gleicht ein alphanumerisches Zeichen ab, das in Klammern aufgelistet oder in Bereichen enthalten ist. Bereiche können nur a-z, A-Z und 0-9 enthalten. Beispielsweise stimmt der Bereich [0-9a-z] mit einer beliebigen Zahl oder einem Kleinbuchstaben überein. [CB]at stimmt beispielsweise mit Cat oder Bat überein, und [1-2]00 stimmt mit 100 und 200 überein.
  • !: Wenn dies am Anfang eines Musters steht, negiert es vorherige positive Muster ins Gegenteil. Es hat keine besondere Bedeutung, wenn es nicht das erste Zeichen ist.

Die Zeichen *, [ und ! sind Sonderzeichen in YAML. Wenn du ein Muster mit *, [ oder ! beginnst, musst du das Muster in Anführungszeichen einschließen. Wenn du eine Ablaufsequenz mit einem Muster verwendest, das [ und/oder ] enthält, muss das Muster zudem in Anführungszeichen gesetzt werden.

# Valid
paths:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

Weitere Informationen zur Syntax der Branch-, Tag- und Pfadfilter findest du unter on.<push>.<branches|tags>, on.<pull_request>.<branches|tags> und on.<push|pull_request>.paths.

Muster für den Abgleich von Branches und Tags

MusterBESCHREIBUNGBeispiele für Übereinstimmungen
feature/*Das Platzhalterzeichen * gleicht ein beliebiges Zeichen ab, nicht jedoch den Schrägstrich (/).feature/my-branch

feature/your-branch
feature/**Das Platzhalterzeichen ** gleicht ein beliebiges Zeichen ab, einschließlich des Schrägstrichs (/) in Branch- und Tagnamen.feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

releases/mona-the-octocat
Abgleich mit dem exakten Branch- oder Tag-Namen.main

releases/mona-the-octocat
'*'Dies gleicht alle Branch- und Tagnamen ab, die keinen Schrägstrich (/) enthalten. Das *-Zeichen ist ein Sonderzeichen in YAML. Wenn du ein Muster mit * beginnst, musst du Anführungszeichen verwenden.main

releases
'**'Abgleich mit allen Branch- und Tag-Namen. Dies ist das Standardverhalten, wenn du keinen branches- oder tags-Filter verwendest.all/the/branches

every/tag
'*feature'Das *-Zeichen ist ein Sonderzeichen in YAML. Wenn du ein Muster mit * beginnst, musst du Anführungszeichen verwenden.mona-feature

feature

ver-10-feature
v2*Dies gleicht Branch- und Tagnamen ab, die mit v2 beginnen.v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+Dies gleicht alle Branches und Tags für die semantische Versionierung mit den Hauptversionen 1 oder 2 ab.v1.10.1

v2.0.0

Muster für den Abgleich von Dateinamen

Pfadmuster müssen mit dem gesamten Pfad übereinstimmen und mit dem Root des Repositorys beginnen.

MusterBeschreibung der ÜbereinstimmungenBeispiele für Übereinstimmungen
'*'Das Platzhalterzeichen * gleicht ein beliebiges Zeichen ab, nicht jedoch den Schrägstrich (/). Das *-Zeichen ist ein Sonderzeichen in YAML. Wenn du ein Muster mit * beginnst, musst du Anführungszeichen verwenden.README.md

server.rb
'*.jsx?'Das ?-Zeichen gleicht null oder mehrere der vorherigen Zeichen ab.page.js

page.jsx
'**'Das Platzhalterzeichen ** gleicht ein beliebiges Zeichen einschließlich Schrägstrich (/) ab. Dies ist das Standardverhalten, wenn du keinen path-Filter verwendest.all/the/files.md
'*.js'Das Platzhalterzeichen * gleicht ein beliebiges Zeichen ab, nicht jedoch den Schrägstrich (/). Dies gleicht alle .js-Dateien im Stamm des Repositorys ab.app.js

index.js
'**.js'Dies gleicht alle .js-Dateien im Repository ab.index.js

js/index.js

src/js/app.js
docs/*Dies gleicht alle Dateien im Stamm des docs-Verzeichnisses im Stamm des Repositorys ab.docs/README.md

docs/file.txt
docs/**Dies gleicht beliebige Dateien im /docs-Verzeichnis im Stamm des Repositorys ab.docs/README.md

docs/mona/octocat.txt
docs/**/*.mdDies gleicht eine Datei mit einem .md-Suffix an einer beliebigen Stelle im docs-Verzeichnis ab.docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'Dies gleicht alle Dateien in einem docs-Verzeichnis an einer beliebigen Stelle im Repository ab.docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc
'**/README.md'Eine Datei mit dem Namen „README.md“ an beliebiger Stelle im Repository.README.md

js/README.md
'**/*src/**'Dies gleicht eine beliebige Datei in einem Ordner mit einem src-Suffix an einer beliebigen Stelle im Repository ab.a/src/app.js

my-src/code/js/app.js
'**/*-post.md'Dies gleicht eine Datei mit dem Suffix -post.md an einer beliebigen Stelle im Repository ab.my-post.md

path/their-post.md
'**/migrate-*.sql'Dies gleicht eine Datei mit dem Präfix migrate- und dem Suffix .sql an einer beliebigen Stelle im Repository ab.migrate-10909.sql

db/migrate-v1.0.sql

db/sept/migrate-v1.sql
'*.md'

'!README.md'
Durch die Verwendung eines Ausrufezeichens (!) vor einem Muster wird dieses negiert. Wenn eine Datei sowohl mit einem Muster übereinstimmt als auch mit einem negativen Muster, das später in der Datei definiert ist, wird die Datei nicht berücksichtigt.hello.md

Stimmt nicht überein mit

README.md

docs/hello.md
'*.md'

'!README.md'

README*
Die Muster werden sequenziell geprüft. Wenn ein Muster ein vorangegangenes Muster negiert, werden die Dateipfade wieder berücksichtigt.hello.md

README.md

README.doc