Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Workflowsyntax für GitHub Actions

In this article

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

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

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 deines Workflows. GitHub zeigt die Namen deiner Workflows auf der Registerkarte „Aktionen“ deines Repositorys an. Wenn du name weglässt, verwendet GitHub hierfür den Workflowdateipfad relativ zum Stammverzeichnis des Repositorys.

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, die Workflows auslösen.

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 jedem Ereignis und den zugehörigen 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 jedem Ereignis und den zugehörigen 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 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 im „Filtermuster-Spickzettel“.

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/**'

Beispiel: Ausschließen von Branches

Wenn ein Muster dem Muster branches-ignore entspricht, wird der Workflow nicht ausgeführt. Die in branches 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 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 im Spickzettel zu Filtermustern.

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 beta/3-alpha (refs/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 du sowohl branches/branches-ignore als auch paths 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 auf dem Filtermuster-Spickzettel.

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'

Hinweis: 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. Weitere Informationen findest du unter Handhabung übersprungener, jedoch erforderlicher Überprüfungen.

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 du Pfadmuster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchtest, verwende den Filter paths zusammen mit dem 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 du Muster definierst, 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 Vergleichen 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, die Workflows auslösen.

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, die Workflows auslösen.

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.

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

Beispiel

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

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

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 auf dem „Filtermuster-Spickzettel“.

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

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

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

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

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

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 Authentifizierung in einem Workflow.

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.

Verfügbare Bereiche und Zugriffswerte:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: 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 Lese- oder Schreibzugriff für alle verfügbaren Bereiche zu definieren:

permissions: read-all|write-all

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

permissions: {}
``` 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](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks).

### Beispiel: Zuweisen von Berechtigungen zu GITHUB_TOKEN

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.

```yaml
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

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 den github-Kontext 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 Workflow, der dieselbe Übereinstimmungsgruppe im Repository verwendet, in Bearbeitung ist, wird pending der Warteschlangeauftrag oder der Workflow ausgeführt. Alle zuvor anhängigen Aufträge oder Workflows in der Parallelitätsgruppe werden abgebrochen. Du kannst auch mit cancel-in-progress: true alle derzeit ausgeführten Aufträge oder Workflows in derselben Parallelitätsgruppe abbrechen.

Beispiele: Verwenden der Parallelität und des Standardverhaltens

concurrency: staging_environment
concurrency: ci-${{ github.ref }}

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

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

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 findest du unter Nutzungseinschränkungen und Abrechnung für auf GitHub gehostete Runner und unter Informationen zu selbstgehosteten Runnern für Nutzungseinschränkungen für selbstgehostete Runner.

Wenn du den eindeutigen Bezeichner eines Auftrags in einer Workflowausführung ermitteln musst, kannst du die GitHub Enterprise Server-API verwenden. Weitere Informationen findest du unter Workflowaufträge.

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 Authentifizierung in einem Workflow.

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.

Verfügbare Bereiche und Zugriffswerte:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: 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 Lese- oder Schreibzugriff für alle verfügbaren Bereiche zu definieren:

permissions: read-all|write-all

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

permissions: {}
``` 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](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks).

#### Beispiel: Festlegen von Berechtigungen für einen bestimmten Auftrag

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.

```yaml
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, 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 auf alle Aufträge in der Abhängigkeitskette ab dem Fehlerpunkt angewendet.

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 Kontextverfügbarkeit.

Wenn du Ausdrücke in einer if-Bedingung verwendest, kannst du die Syntax des Ausdrucks (${{ }}) weglassen, weil GitHub automatisch die if-Bedingung als Ausdruck wertet. 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@v3
      - 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 selbstgehosteter Runner sein.

  • Du kannst Runner basierend auf den ihnen zugewiesenen Bezeichnungen als Ziel festlegen.

  • Du kannst runs-on als einzelne Zeichenfolge oder als Array von Zeichenfolgen bereitstellen.

  • Wenn du ein Array von Zeichenfolgen angibst, wird dein Workflow auf jedem Runner ausgeführt, der allen angegebenen runs-on-Werten entspricht.

  • Wenn du deinen Workflow auf mehreren Computern ausführen möchtest, verwende jobs.<job_id>.strategy.

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

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 Arten von GitHub-gehostete Runnern sind:

Runner-Image YAML-Workflow-Kennzeichnung Hinweise
Windows Server 2022 windows-latest oder windows-2022 Die windows-latest-Bezeichnung verwendet derzeit das Windows Server 2022-Runner-Image.
Windows Server 2019 windows-2019
Ubuntu 22.04 ubuntu-latest oder ubuntu-22.04 Die ubuntu-latest-Bezeichnung verwendet derzeit das Ubuntu 22.04-Runner-Image.
Ubuntu 20.04 ubuntu-20.04
Ubuntu 18.04 [veraltet] ubuntu-18.04 Migriere zu ubuntu-20.04 oder ubuntu-22.04. Weitere Informationen findest du in diesem Blogbeitrag auf GitHub.
macOS Monterey 12 macos-latest oder macos-12 Die macos-latest-Bezeichnung verwendet derzeit das macOS 12-Runner-Image.
macOS Big Sur 11 macos-11
macOS Catalina 10.15 [veraltet] macos-10.15 Migriere zu macOS-11 oder macOS-12. Weitere Informationen findest du in diesem Blogbeitrag auf GitHub.

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 Informationen zu 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 Verwenden von selbstgehosteten Runnern in einem Workflow.

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

Beispiel: Verwenden eines einzelnen Umgebungsnamens

environment: staging_environment

Beispiel: Verwenden von Umgebungsnamen und URL

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

Die URL kann ein Ausdruck sein und kann einen beliebigen Kontext mit Ausnahme des secrets-Kontextsverwenden. 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 }}

jobs.<job_id>.concurrency

Hinweis: Wenn Parallelität auf Auftragsebene angegeben wird, wird die Reihenfolge für Aufträge oder Ausführungen, die der Warteschlange innerhalb eines Zeitraums von bis zu fünf Minuten hinzugefügt werden, nicht garantiert.

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. Der Ausdruck kann einen beliebigen Kontext verwenden. Einzige Ausnahme ist der Kontext secrets. 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 Workflow, der dieselbe Übereinstimmungsgruppe im Repository verwendet, in Bearbeitung ist, wird pending der Warteschlangeauftrag oder der Workflow ausgeführt. Alle zuvor anhängigen Aufträge oder Workflows in der Parallelitätsgruppe werden abgebrochen. Du kannst auch mit cancel-in-progress: true alle derzeit ausgeführten Aufträge oder Workflows in derselben Parallelitätsgruppe abbrechen.

Beispiele: Verwenden der Parallelität und des Standardverhaltens

concurrency: staging_environment
concurrency: ci-${{ github.ref }}

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

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

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 Runnder zensiert und nicht an GitHub Actions gesendet.

Um Auftragsausgaben in einem abhängigen Auftrag zu verwenden, kannst du den needs-Kontext verwenden. Weitere Informationen findest du 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 "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.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

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. Kontext und Ausdruck sind in diesem Abschnitt nicht zulässig.

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

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

Beispiel

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 Kontextverfügbarkeit.

Wenn du Ausdrücke in einer if-Bedingung verwendest, kannst du die Syntax des Ausdrucks (${{ }}) weglassen, weil GitHub automatisch die if-Bedingung als Ausdruck wertet. 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 findest du unter Kontextverfügbarkeit und Verschlüsselte Geheimnisse.

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@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v3
  # Reference a specific version
  - uses: actions/checkout@v3.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.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
      - name: Use local my-action
        uses: ./.github/actions/my-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 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 verschlüsseltes Geheimnis hinzu. Weitere Informationen findest du unter Erstellen eines personal access token und Verschlüsselte Geheimnisse.

Ersetze PERSONAL_ACCESS_TOKEN im Beispiel durch den Namen deines Geheimnisses.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        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

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

Führt Befehlszeilen-Programme über die Betriebssystem-Shell aus. 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
    

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

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}'"
AllpythonFü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 Skripts mithilfe von Bash

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

Beispiel: Ausführen eines Skripts mithilfe der cmd unter Windows

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

Beispiel: Ausführen eines Skripts mithilfe von PowerShell Core

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

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

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

Beispiel: Ausführen eines Python-Skripts

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

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
    run: |
      print %ENV
    shell: perl {0}

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

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:

    • Fail-Fast-Verhalten mit set -eo pipefail: Diese Option wird festgelegt, wenn shell: bash explizit angegeben wird. Sie wird standardmäßig nicht angewendet.
    • Du kannst die volle Kontrolle über Shellparameter übernehmen, indem du einen Vorlagen-String für die Shelloptionen bereitstellst. Beispiel: bash {0}.
    • sh-ähnliche Shells liefern beim Beenden als ihren eigenen Exit-Code den Exit-Code des letzten Befehls, der im Skript ausgeführt wurde. Dies ist auch das Standardverhalten für Aktionen. Der Runner meldet den Status des Schritts gemäß diesem Exit-Code 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.

Beispiel

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.

Beispiel

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

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

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 für die Auftragsausführung findest du unter Nutzungseinschränkungen und Abrechnung 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 Informationen zum GITHUB_TOKEN-Geheimnis.

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 einer Matrix 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 Server 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 Server 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 repository_dispatch-Trigger findest du unter Ereignisse, die Workflows auslösen.

{
  "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 sechs Aufträge 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: [12, 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, bricht GitHub Enterprise Server 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 Server 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:14.16
      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:14.16

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 --network-Option wird 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 Dienstcontainern.

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

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

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 und internen Repositorys.
  • ./.github/workflows/{filename} für wiederverwendbare Workflows im gleichen Repository.

{ref} kann ein SHA-Wert, ein Releasetag oder ein Branchname sein. Die Verwendung des Commit-SHA-Werts ist in Bezug auf Stabilität und Sicherheit am sichersten. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions. Wenn du die zweite Syntaxoption verwendest (ohne {owner}/{repo} und @{ref}), stammt der aufgerufene Workflow aus demselben Commit wieder aufrufende Workflow.

Beispiel

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

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

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

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 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
branches:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
branches:
  - **/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