Workflow-Syntax für GitHub Actions

Ein Workflow ist ein konfigurierbarer automatisierter Prozess, der aus einem oder mehreren Jobs besteht. Du musst eine YAML-Datei erstellen, um Deine Workflow-Konfiguration zu definieren.

GitHub Actions ist verfügbar mit GitHub Free, GitHub Pro, GitHub Free für Organisationen, GitHub Team, GitHub Enterprise Cloud, und GitHub AE. GitHub Actions ist nicht verfügbar für private Repositorys, die im Besitz von Konten mit älteren Pro-Repository-Plänen sind. For more information, see "GitHub's products."

Informationen zur YAML-Syntax für Workflows

Workflow-Dateien verwenden die YAML-Syntax und müssen die Dateierweiterung .yml oder .yaml aufweisen. If you're new to YAML and want to learn more, see "Learn YAML in Y minutes."

Workflow-Dateien müssen im Verzeichnis .github/workflows im Repository gespeichert werden.

name

Name des Workflows. GitHub zeigt die Namen Deiner Workflows auf der Aktionen-Seite Deines Repositorys an. Wenn Du nameweglässt, setzt GitHub den Pfad der Workflow-Datei relativ zum Stammverzeichnis des Repositorys.

on

Required. The name of the GitHub event that triggers the workflow. Sie können einen string für ein einzelnes Ereignis, ein array mit Ereignissen, ein array mit Ereignis-types oder eine Ereigniskonfigurations-map festlegen, mit der ein Workflow geplant oder die Ausführung eines Workflows auf bestimmte Dateien, Tags oder Branch-Änderungen beschränkt wird. Eine Liste der verfügbaren Ereignisse finden Sie unter „Ereignisse, die Workflows auslösen“.

Example: Using a single event
# Triggered when code is pushed to any branch in a repository
on: push
Example: Using a list of events
# Triggers the workflow on push or pull request events
on: [push, pull_request]
Example: Using multiple events with activity types or configuration

Wenn Du Aktivitätstypen oder Konfigurationen für ein Ereignis angeben musst, musst Du jedes Ereignis separat konfigurieren. Du musst einen Doppelpunkt (:) an alle Ereignisse anhängen, einschließlich Ereignisse ohne Konfiguration.

on:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  # Also trigger on page_build, as well as release created events
  page_build:
  release:
    types: # This configuration does not affect the page_build event above
      - created

on.<event_name>.types

Legt die Aktivitätstypen fest, die die Ausführung eines Workflows auslösen. Die meisten GitHub-Ereignisse werden von mehreren Aktivitätstypen ausgelöst. Beispielsweise wird das Ereignis für die Veröffentlichungsressource ausgelöst, wenn eine Veröffentlichung veröffentlicht (published), erstellt (created), bearbeitet (edited), gelöscht (deleted), vorab veröffentlicht (prereleased) oder ihre Veröffentlichung zurückgezogen (unpublished) wird. Mit dem Stichwort types grenzt Du die Aktivitäten ein, die die Ausführung des Workflows auslösen. Wird ein Webhook-Ereignis nur von einem einzigen Aktivitätstyp ausgelöst, ist das Stichwort types nicht erforderlich.

Du kannst ein Array mit Ereignis-types benutzen. Weitere Informationen zu den einzelnen Ereignissen und den zugehörigen Aktivitätstypen findest Du unter „Ereignisse, die Workflows auslösen“.

# Workflow bei Pull-Request-Aktivität auslösen
on:
  release:
    # Gib das Stichwort "types" nur dann an, wenn die Aktivitätstypen, die den Workflow auslösen, eingegrenzt werden sollen.
    types: [published, created, edited]

on.<push|pull_request>.<branches|tags>

Wenn Sie die Ereignisse push und pull_request verwenden, können Sie einen Workflow so konfigurieren, dass er auf bestimmten Branches oder Tags ausgeführt wird. Für ein pull_request-Ereignis werden nur Branches und Tags auf der Basis ausgewertet. Wenn Du nur tags oder nur branches definierst, wird der Workflow bei Ereignissen, die sich auf die nicht definierte Git-Ref auswirken, nicht ausgeführt.

Die Schlüsselwörter branches, branches-ignore, tags und tags-ignore akzeptieren Glob-Muster, bei denen mithilfe der Platzhalterzeichen * und ** mehrere passende Branch- oder Tag-Namen gefunden werden. Weitere Informationen findest Du auf dem „Spickzettel zu Filtermustern“.

Example: Including branches and tags

Die in branches und tags definierten Muster werden anhand des Namens des Git-Ref ausgewertet. Wenn Du das Muster mona/octocat in branches definierst, passt beispielsweise die Git-Ref refs/heads/mona/octocat. Zu dem Muster releases/** passt die Git-Ref refs/heads/releases/10.

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      # Push events on main branch
      - main
      # Push events to branches matching refs/heads/mona/octocat
      - 'mona/octocat'
      # Push events to branches matching refs/heads/releases/10
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v1             # Push events to v1 tag
      - v1.*           # Push events to v1.0, v1.1, and v1.9 tags

Example: Ignoring branches and tags

Wenn ein Muster mit dem Muster branches-ignore oder tags-ignore übereinstimmt, wird der Workflow nicht ausgeführt. Die in branches-ignore und tags-ignore definierten Muster werden anhand des Namens der Git-Ref ausgewertet. Wenn Du das Muster mona/octocat in branches definierst, passt beispielsweise die Git-Ref refs/heads/mona/octocat. Das Muster releases/**-alpha in branches passt zu der Git-Ref refs/releases/beta/3-alpha.

on:
  push:
    # Folge von Mustern zum Abgleich mit refs/heads
    branches-ignore:
      # Push-Ereignisse zu Branches, die zu refs/heads/mona/octocat passen
      - 'mona/octocat'
      # Push-Ereignisse zu Branches, die zu refs/heads/releases/beta/3-alpha passen
      - 'releases/**-alpha'
    # Folge von Mustern zum Abgleich mit refs/tags
    tags-ignore:
      - v1.*           # Push-Ereignisse zu den Tags v1.0, v1.1 und v1.9

Branches und Tags ausschließen

Es stehen zwei Arten von Filtern zur Verfügung, mit denen Du die Ausführung eines Workflows bei Push-Vorgängen und Pull-Requests an Tags und Branches unterbinden kannst.

  • branches oder branches-ignore - Du kannst die beiden Filter branches und branches-ignore nicht gleichzeitig für dasselbe Ereignis in einem Workflow verwenden. Mit dem Filter branches kannst Du die Branches auf positive Übereinstimmungen filtern und Branches ausschließen. Nutze den Filter branches-ignore, wenn Du lediglich Branch-Namen ausschließen musst.
  • tags oder tags-ignore - Du kannst die beiden Filter tags und den Filter tags-ignore nicht gleichzeitig für dasselbe Ereignis in einem Workflow verwenden. Mit dem Filter tags kannst Du die Tags auf positive Übereinstimmungen filtern und Tags ausschließen. Nutze den Filter branches-ignore, wenn Du lediglich Tag-Namen ausschließen musst.

Example: Using positive and negative patterns

Mit dem Zeichen ! kannst Du tags und branches ausschließen. Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.

  • Wenn eine Übereinstimmung mit einem negativen Muster (mit vorangestelltem !) nach einem positiven Abgleich vorliegt, wird die Git-Ref ausgeschlossen.
  • Ein übereinstimmendes positives Muster nach einem negativen Abgleich schließt die Git-Ref wieder ein.

Der folgende Workflow wird bei Push-Vorgängen an releases/10 oder releases/beta/mona ausgeführt, nicht jedoch bei Push-Vorgängen an releases/10-alpha oder releases/beta/3-alpha, da das negative Muster !releases/**-alpha nach dem positiven Muster steht.

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

on.<push|pull_request>.paths

Bei den Ereignissen push und pull_request kannst Du einen Workflows zur Ausführung konfigurieren, wenn mindestens eine Datei nicht zu den paths-ignore passt oder mindestens eine geänderte Datei zu den konfigurierten paths passt. Bei Push-Vorgängen zu Tags werden Pfadfilter nicht ausgewertet.

Unter den Schlüsselwörtern paths-ignore und paths kannst Du Glob-Muster nutzen, so dass mithilfe der Platzhalterzeichens * und ** mehrere Pfadnamen passen. Weitere Informationen findest Du auf dem „Spickzettel zu Filtermustern“.

Example: Ignoring paths

When all the path names match patterns in paths-ignore, the workflow will not run. GitHub wertet die in paths-ignore definierten Muster anhand des Pfadnamens aus. Ein Workflow mit dem nachfolgenden Pfadfilter wird nur bei push-Ereignissen ausgeführt, bei denen sich mindestens eine Datei außerhalb des Verzeichnisses docs im Root des Repositorys befindet.

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

Example: Including paths

Wenn mindestens ein Pfad zu einem Muster im Filter paths passt, wird der Workflow ausgeführt. Soll bei jedem Push-Vorgang einer JavaScript-Datei ein Build ausgelöst werden, gibst Du ein Muster mit Platzhalterzeichen an.

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

Pfade ausschließen

Pfade können mit zwei Arten von Filtern ausgeschlossen werden. Du kannst nicht beide Filter gleichzeitig für dasselbe Ereignis in einem Workflow nutzen.

  • paths-ignore - Verwende den Filter paths-ignore, wenn Du lediglich Pfadnamen ausschließen musst.
  • paths - Mit dem Filter paths kannst Du die Pfade auf positive Übereinstimmungen filtern und Pfade ausschließen.

Example: Using positive and negative patterns

Mit dem Zeichen ! kannst Du paths ausschließen. Die Reihenfolge, in der Sie Muster definieren, ist entscheidend:

  • Wenn nach einem positiven Abgleich ein negatives Muster (mit vorangestelltem !) passt, wird der Pfad ausgeschlossen.
  • Ein passendes positives Muster nach einem negativen Abgleich schließt den Pfad wieder ein.

Dieses Beispiel wird stets ausgeführt, wenn das push-Ereignis eine Datei im Verzeichnis sub-project oder in einem Unterverzeichnis davon umfasst, jedoch nur dann, wenn sich die Datei nicht im Verzeichnis sub-project/docs befindet. Ein Push-Vorgang, mit dem beispielsweise die Datei sub-project/index.js oder sub-project/src/index.js geändert wird, löst eine Ausführung des Workflows aus, aber ein Push-Vorgang, mit dem lediglich sub-project/docs/readme.md geändert wird, tut dies nicht.

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 Zeitüberschreitung nicht erzeugt (zu große Diffs), wird der Workflow in jedem Fall ausgeführt.

Zur Ermittlung, ob ein Workflow ausgeführt werden soll, wertet der Filter die geänderten Dateien anhand der Liste 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 jüngsten Version des Themen-Branches und jenem Commit, bei welchem der Themen-Branch zuletzt mit dem Basis-Branch synchronisiert wurde.
  • Push-Vorgänge an bestehende Branches: Eine Two-Dot-Diff vergleicht die Kopf- und Basis-SHAs direkt miteinander.
  • Push-Vorgänge an neue Branches: Ein Two-Dot-Diff wird mit dem übergeordneten Element des Vorgängers des tiefsten gepushten Commits durchgeführt.

Weitere Informationen findest Du unter „Informationen zum Vergleich von Branches in Pull-Requests“.

on.schedule

Du kannst einen Workflow mit Hilfe von POSIX cron syntax 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 Sie geplante Workflows ausführen können, ist einmal alle 5 Minuten.

This example triggers the workflow every day at 5:30 and 17:30 UTC:

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

Weitere Informationen zur Cron-Syntax findest Du unter „Ereignisse, die Workflows auslösen“.

permissions

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. For more information, see "Authentication in a workflow."

You can use permissions either as a top-level key, to apply to all jobs in the workflow, or within specific jobs. When you add the permissions key within a specific job, all actions and run commands within that job that use the GITHUB_TOKEN gain the access rights you specify. For more information, see jobs.<job_id>.permissions.

Available scopes and access values:

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

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the permissions key to add and remove read permissions for forked repositories, but typically you can't grant write access. The exception to this behavior is where an admin user has selected the Send write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, see "Disabling or limiting GitHub Actions for a repository."

Beispiel

This example shows permissions being set for the GITHUB_TOKEN that will apply to all jobs in the workflow. All permissions are granted read access.

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

A map of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

Wenn mehr als eine Umgebungsvariable mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Umgebungsvariable. Beispielsweise wird eine in einem Schritt definierte Umgebungsvariable die Auftrags- und Workflow-Variablen mit dem gleichen Namen überschreiben, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Variable überschreibt die Workflow-Variable mit dem gleichen Namen, während der Auftrag ausgeführt wird.

Beispiel

env:
  SERVER: production

defaults

Eine map der Standardeinstellungen, die für alle Jobs 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 Standardeinstellungen der Optionen shell und working-directory (Arbeitsverzeichnis) für alle run-Schritte in einem Workflow angeben. Du kannst auch Standardeinstellungen für run festlegen, die nur für einen Job 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

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

concurrency

Note: Concurrency is currently in beta and subject to change.

Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can only use the github context. For more information about expressions, see "Context and expression syntax for GitHub Actions."

You can also specify concurrency at the job level. For more information, see jobs.<job_id>.concurrency.

When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. Any previously pending job or workflow in the concurrency group will be canceled. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true.

Examples: Using concurrency and the default behavior
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
Example: Using concurrency to cancel any in-progress job or run
concurrency: 
  group: ${{ github.head_ref }}
  cancel-in-progress: true

jobs

Ein Workflow-Lauf besteht aus mindestens einem Job. Die Aufträge werden standardmäßig parallel ausgeführt. Sollen Jobs sequenziell ausgeführt werden, kannst Du mit dem Schlüsselwort jobs.<job_id>.needs eine Abhängigkeit von anderen Jobs definieren.

Each job runs in a runner environment specified by runs-on.

Innerhalb der Nutzungsbeschränkungen des Workflows kannst Du unbegrenzt viele Jobs ausführen. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Wenn Du den eindeutigen Bezeichner eines Jobs finden musst, der in einem Workflowlauf ausgeführt wird, kannst Du die API von GitHub verwenden. For more information, see "Workflow Jobs."

jobs.<job_id>

Jedem Auftrag muss eine ID zugewiesen sein. Das Stichwort job_id ist ein String, und der Wert umfasst eine Zuordnung der Konfigurationsdaten für den Auftrag. Sie müssen <job_id> durch einen eindeutigen String für das jobs-Objekt ersetzen. Die <job_id> muss mit einem Buchstaben oder einem Unterstrich (_) beginnen und darf nur alphanumerische Zeichen, Bindestriche (-) und Unterstriche (_) enthalten.

Beispiel

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

jobs.<job_id>.name

Name des Auftrags, der auf GitHub angezeigt wird.

jobs.<job_id>.needs

Liste mit allen Aufträgen, die erfolgreich abgeschlossen sein müssen, bevor dieser Auftrag ausgeführt wird. Hier ist ein String oder ein Array mit Strings zulässig. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.

Example: Requiring dependent jobs to be successful

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

In diesem Beispiel muss job1 erfolgreich abgeschlossen werden, bevor job2 beginnt, und job3 wartet ab, bis sowohl job1 als auch job2 abgeschlossen sind.

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

  1. job1
  2. job2
  3. job3

Example: Not requiring dependent jobs to be successful

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

In this example, job3 uses the always() conditional expression so that it always runs after job1 and job2 have completed, regardless of whether they were successful. For more information, see "Context and expression syntax."

jobs.<job_id>.runs-on

Required. The type of machine to run the job on. Die Maschine kann entweder ein GitHub-gehosteter oder ein selbst-gehosteter Runner sein.

GitHub-gehostete Runner

Wenn Du einen GitHub-gehosteten Runner verwendest, läuft jeder Job in einer frischen Instanz einer virtuellen Umgebung, die mit runs-on angegeben wurde.

Verfügbare Arten von GitHub-gehostete Runnern sind:

Warning: Ubuntu 16.04 is being deprecated. If any of your workflows use Ubuntu 16.04, migrate to Ubuntu 20.04 or 18.04. For more information, see the blog post.

Virtuelle UmgebungYAML-Workflow-Kennzeichnung
Windows Server 2019windows-latest oder windows-2019
Windows Server 2016windows-2016
Ubuntu 20.04ubuntu-latest oder ubuntu-20.04
Ubuntu 18.04ubuntu-18.04
macOS Big Sur 11macos-11
macOS Catalina 10.15macos-latest or macos-10.15

Note: The macOS 11 virtual environment is currently provided as a private preview only. Any users or organizations that are already using this runner can continue using it, but we're not accepting any further users or organizations at this time. The macos-latest YAML workflow label still uses the macOS 10.15 virtual environment.

Beispiel
Runs-on: ubuntu-latest

Weitere Informationen findest Du unter "Virtuelle Umgebungen für GitHub-gehostete Runner."

Selbst-gehostete Runner

Um einen selbst-gehosteten Läufer für Deinen Auftrag anzugeben, konfiguriere runs-on in Deiner Workflow-Datei mit selbst gehosteten Läuferkennzeichnungen.

Alle selbst gehosteten Läufer haben die Kennzeichnung self-hosted und Du kannst jeden selbst-gehosteten Läufer auswählen, indem Du nur die Kennzeichnung self-hosted bereitstellst. Alternativ kannst Du self-hosted in einer Matrix mit zusätzlichen Kennzeichnungen verwenden, beispielsweise Kennzeichnungen für ein bestimmtes Betriebssystem oder Systemarchitektur, um nur die von Ihnen spezifizierten Läufertypen auszuwählen.

Beispiel
runs-on: [self-hosted, linux]

Weitere Informationen findest Du unter „Informationen zu selbst-gehosteten Runnern“ und „Selbst-gehostete Runner in einem Workflow verwenden“.

jobs.<job_id>.permissions

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access. For more information, see "Authentication in a workflow."

By specifying the permission within a job definition, you can configure a different set of permissions for the GITHUB_TOKEN for each job, if required. Alternatively, you can specify the permissions for all jobs in the workflow. For information on defining permissions at the workflow level, see permissions.

Available scopes and access values:

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

If you specify the access for any of these scopes, all of those that are not specified are set to none.

You can use the following syntax to define read or write access for all of the available scopes:

permissions: read-all|write-all

You can use the permissions key to add and remove read permissions for forked repositories, but typically you can't grant write access. The exception to this behavior is where an admin user has selected the Send write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, see "Disabling or limiting GitHub Actions for a repository."

Beispiel

This example shows permissions being set for the GITHUB_TOKEN that will only apply to the job named stale. Write access is granted for the issues and pull-requests scopes. All other scopes will have no access.

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v3

jobs.<job_id>.environment

The environment that the job references. All environment protection rules must pass before a job referencing the environment is sent to a runner. For more information, see "Environments."

You can provide the environment as only the environment name, or as an environment object with the name and url. The URL maps to environment_url in the deployments API. For more information about the deployments API, see "Deployments."

Example using a single environment name
environment: staging_environment
Example using environment name and URL
environment:
  name: production_environment
  url: https://github.com

The URL can be an expression and can use any context except for the secrets context. For more information about expressions, see "Context and expression syntax for GitHub Actions."

Beispiel

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

jobs.<job_id>.concurrency

Note: Concurrency is currently in beta and subject to change.

Note: When concurrency is specified at the job level, order is not guaranteed for jobs or runs that queue within 5 minutes of each other.

Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context. For more information about expressions, see "Context and expression syntax for GitHub Actions."

You can also specify concurrency at the workflow level. For more information, see concurrency.

When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. Any previously pending job or workflow in the concurrency group will be canceled. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true.

Examples: Using concurrency and the default behavior
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
Example: Using concurrency to cancel any in-progress job or run
concurrency: 
  group: ${{ github.head_ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

Eine map der Ausgaben eines Jobs. Ausgaben eines Jobs stehen allen nachgelagerten Jobs zur Verfügung, die von diesem Job abhängen. Weitere Informationen zur Definition von Abhängigkeiten zwischen Jobs findest Du unter Jobs.<job_id>.needs.

Ausgaben von Jobs sind Zeichenketten und wenn sie Ausdrücke enthalten, werden diese am Ende jedes Jobs auf dem Runner ausgewertet. Ausgaben, die Geheimnisse enthalten, werden auf dem Runnder zensiert und nicht an GitHub Actions gesendet.

Um Jobausgaben in einem abhängigen Job zu verwenden, kannst Du den Kontext needs verwenden. Weitere Informationen findest Du unter "Kontext- und Ausdrucks-Syntax für GitHub Actions".

Beispiel

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

Eine map mit Umgebungsvariablen, die für alle Schritte im Auftrag verfügbar sind. Darüber hinaus können Sie Umgebungsvariablen für den gesamten Workflow oder für einen einzelnen Schritt festlegen. For more information, see env and jobs.<job_id>.steps[*].env.

Wenn mehr als eine Umgebungsvariable mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Umgebungsvariable. Beispielsweise wird eine in einem Schritt definierte Umgebungsvariable die Auftrags- und Workflow-Variablen mit dem gleichen Namen überschreiben, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Variable überschreibt die Workflow-Variable mit dem gleichen Namen, während der Auftrag ausgeführt wird.

Beispiel

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Eine map mit Standardeinstellungen, die für alle Schritte im Job gelten. Du kannst auch Standardeinstellungen für den gesamten Workflow festlegen. Weitere Informationen findest Du unter Standardwerte.

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

Standards für shell und working-directory (Arbeitsverzeichnis) bereitstellen, die für alle run-Schritte des Jobs gelten. Kontext und Ausdruck sind in diesem Abschnitt nicht zulässig.

Du kannst Standardeinstellungen der Optionen shell und working-directory (Arbeitsverzeichnis) für alle run-Schritte in einem Job angeben. Du kannst auch Standardeinstellungen für run für den gesamten Workflow 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

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

jobs.<job_id>.if

Mit der if-Bedingung geben Sie an, dass ein Auftrag nur dann ausgeführt werden soll, wenn eine bestimmte Bedingung erfüllt ist. Du kannst eine Bedingung mit jedem unterstützten Kontext und Ausdruck erstellen.

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression, unless the expression contains any operators. If the expression contains any operators, the expression must be contained within ${{ }} to explicitly mark it for evaluation. Weitere Informationen findest Du unter „Kontext- und Ausdruckssyntax für GitHub Actions“.

jobs.<job_id>.steps

Ein Auftrag enthält eine Sequenz von Aufgaben, sogenannten steps. Mit Schritten können Befehle oder Einrichtungsaufgaben ausgeführt werden, und außerdem Aktionen, die sich in Ihrem Repository oder in einem öffentlichen Repository befinden oder in einer Docker Registry veröffentlicht sind. Nicht alle Schritte führen eine Aktion 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 ausgeführt werden, werden Änderungen an den Umgebungsvariablen nicht von Schritt zu Schritt 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. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

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

Eindeutige Kennung für den Schritt. Anhand der id können Sie in Kontexten auf den Schritt verweisen. Weitere Informationen findest Du unter „Kontext- und Ausdrucks-Syntax für GitHub Actions“.

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

Mit der Bedingung if gibst Du an, dass ein Schritt nur dann ausgeführt werden soll, wenn eine bestimmte Bedingung erfüllt ist. Du kannst eine Bedingung mit jedem unterstützten Kontext und Ausdruck erstellen.

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression, unless the expression contains any operators. If the expression contains any operators, the expression must be contained within ${{ }} to explicitly mark it for evaluation. Weitere Informationen findest Du unter „Kontext- und Ausdruckssyntax für GitHub Actions“.

Example: Using contexts

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

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.

Example: Using status check functions

my backup step wird nur dann ausgeführt, wenn der vorherige Schritt eines Auftrags fehlschlägt. Weitere Informationen findest Du unter „Kontext- und Ausdrucks-Syntax für GitHub Actions“.

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

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 Auftrag ausgeführt wird. Eine Aktion ist eine wiederverwendbare Code-Einheit. Sie können eine Aktion verwenden, die im selben Repository wie der Workflow, in einem öffentlichen Repository oder in einem veröffentlichten Docker-Container-Image definiert ist.

Es wird dringend empfohlen, die verwendete Version der Aktion zu nennen (Git-Ref, SHA oder Docker-Tag-Nummer angeben). Wenn Sie keine Version angeben, könnten damit die Workflows gestört werden, oder es wird ein unerwartetes Verhalten hervorgerufen, wenn der Inhaber 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 Du Dich auf die Hauptversion der Aktion beziehst, kannst Du kritische Fehlerbehebungen und Sicherheits-Patches erhalten und gleichzeitig die Kompatibilität wahren. Außerdem ist damit sichergestellt, dass der Workflow weiterhin problemlos arbeiteten sollte.
  • Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Für einige Aktionen sind Eingaben erforderlich, die Du mit dem Schlüsselwort with festlegen musst. Die erforderlichen Eingaben finden Sie in der README-Datei der Aktion.

Aktionen sind entweder JavaScript-Dateien oder Docker-Container. Bei Docker-Containern als Aktion mmusst Du den Job in einer Linux-Umgebung ausführen. Weitere Details findest Du unter runs-on.

Example: Using versioned actions

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Example: Using a public action

{owner}/{repo}@{ref}

Du kannst einen bestimmten Branch, eine bestimmte Ref oder eine bestimmte SHA in einem öffentlichen Repository auf GitHub heranziehen.

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

Example: Using a public action in a subdirectory

{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

Example: Using an action in the same repository as the workflow

./path/to/dir

Der Pfad zum Verzeichnis, in dem sich die Aktion im Workflow-Repository befindet. Du musst Dein Repository auschecken, bevor Du die Aktion verwendest.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        uses: ./.github/actions/my-action

Example: Using a Docker Hub action

docker://{image}:{tag}

Ein Docker-Image, das auf Docker Hub veröffentlicht ist.

jobs:
  my_first_job:
    Schritte:
      - Name: Mein erster Schritt
        verwendet: docker://alpine:3.8
Example: Using the GitHub Packages Container registry

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

A Docker image in the GitHub Packages Container registry.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://ghcr.io/OWNER/IMAGE_NAME
Example: Using a Docker public registry action

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

Ein Docker-Image in einer öffentlichen Registry. This example uses the Google Container Registry at gcr.io.

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

Example: Using an action inside a different private repository than the workflow

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        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 Befehl run angegebene Text als Name für den Schritt übernommen.

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 „Bestimmte Shell verwenden“.

Jedes Schlüsselwort run 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. Ein Beispiel:

  • Einzeiliger Befehl:

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

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

Mit dem Schlüsselwortworking-directory gibst Du das Arbeitsverzeichnis an, in dem der Befehl ausgeführt werden soll.

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

Bestimmte Shell verwenden

Du kannst die Einstellungen zur Standard-Shell im Betriebssystem des Läufers mit dem Schlüsselwort shell überschreiben. Du kannst die integrierten shell-Schlüsselwörter verwenden oder eine benutzerdefinierte Menge von Shell-Optionen festlegen.

Unterstützte PlattformParameter shellBeschreibungIntern ausgeführter Befehl
AllebashDie standardmäßige Shell für alle Plattformen außer Windows 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}
AllepwshDer PowerShell Core. GitHub hängt die Erweiterung .ps1 an Deinen Skriptnamen an.pwsh -command ". '{0}'"
AllepythonFührt den Befehl Python aus.python {0}
Linux / macOSshDas Fallback-Verhalten für alle Betriebssystem-Plattformen außer Windows, falls keine Shell angegeben ist und bash nicht im Pfad gefunden wird.sh -e {0}
WindowscmdGitHub hängt 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 hängt die Erweiterung .ps1 an Deinen Skriptnamen an. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead.pwsh -command ". '{0}'".
WindowspowershellThe PowerShell Desktop. GitHub hängt die Erweiterung .ps1 an Deinen Skriptnamen an.powershell -command ". '{0}'".

Example: Running a script using bash

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

Example: Running a script using Windows cmd

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

Example: Running a script using PowerShell Core

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

Example: Using PowerShell Desktop to run a script

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

Example: Running a python script

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

Benutzerdefinierte Shell

Mit command […options] {0} [..more_options] kannst Du einen Vorlagen-String für den Wert shell festlegen. GitHub interpretiert das erste Wort im String, nach dem ein Leerzeichen steht, als Befehl, und der Dateiname für das temporäre Skript wird in {0} eingefügt.

Ein Beispiel:

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

The command used, perl in this example, must be installed on the runner.

For information about the software included on GitHub-hosted runners, see "Specifications for GitHub-hosted runners."

Exit-Codes und Voreinstellung für Fehleraktionen

Für integrierte Shell-Stichwö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 behavior using set -eo pipefail: Default for bash and built-in shell. Dies ist außerdem der Standard, wenn Du eine Option für eine Plattform außer Windows angibst.
    • Wenn Du auf Fail-Fast verzichtest und stattdessen die volle Kontrolle übernehmen möchtest, stelle einen Vorlagen-String für die Shell-Optionen bereit. 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 pwsh und der integrierten Shell powershell setzen wir $ErrorActionPreference = 'stop' vor den Inhalt des Skripts.
    • An Powershell-Skripte hängen wir if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } an, sodass der Status der Aktionen den letzten Exit-Code im Skript wiedergibt.
    • Die Benutzer können jederzeit auf die integrierte Shell verzichten und eine benutzerdefinierte Shell-Option angeben, beispielsweise pwsh -File {0} oder powershell -Command "& '{0}'", je nach Bedarf.
  • 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 will exit with the error level of the last program it executed, and it will return the error code to the runner. Dieses Verhalten ist intern mit dem vorherigen Standardverhalten von sh und pwsh konsistent und ist der Standard für cmd.exe, weshalb dieses Verhalten unverändert bleibt.

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

Eine map der Eingabeparameter, die in der Aktion definiert sind. Jeder Eingabeparameter ist ein Schlüssel-Wert-Paar. Eingabeparameter werden als Umgebungsvariablen festgelegt. Die Variable erhält das Präfix INPUT_ und wird in Großbuchstaben umgewandelt.

Beispiel

Definiert die drei Eingabeparameter (first_name, middle_name und last_name), die in der Aktion hello_world definiert sind. Diese Eingabevariablen sind für die Aktion hello-world als 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

Ein string, der die Eingaben für einen Docker-Container definiert. Beim Start des Containers übergibt GitHub die args-Anweisung an den ENTRYPOINT des Containers. Ein array of strings wird von diesem Parameter nicht unterstützt.

Beispiel

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

Die args-Anweisungen werden anstelle der CMD-Anweisung in einem Dockerfile verwendet. Falls Sie CMD in Ihrem Dockerfile verwenden, sollten Sie sich an die nach Präferenz angeordneten Richtlinien halten:

  1. Dokumentiere die erforderlichen Argumente in der README der Aktion und lasse sie in der CMD-Anweisung weg.
  2. Verwenden Sie Standardwerte, die die Verwendung der Aktion ohne Angabe von args erlauben.
  3. Wenn die Aktion einen Schalter --help oder Ähnliches anbietet, verwende diesen als Standard, um eine selbstständige Dokumentation der Aktion herbeizuführen.

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

Überschreibt den Docker-ENTRYPOINT im Dockerfile oder legt ihn fest, sofern er noch nicht angegeben wurde. Im Gegensatz zur Docker ENTRYPOINT-Anweisung, die eine Shell- und eine ausführbare Form aufweist, akzeptiert das Stichwort entrypoint nur einen einzigen Schritt, der die entsprechende ausführbare Datei definiert.

Beispiel

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

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

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

Legt Umgebungsvariablen für Schritte fest, die in der Runner-Umgebung verwendet werden sollen. Darüber hinaus kannst Du Umgebungsvariablen 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 Umgebungsvariable. Beispielsweise wird eine in einem Schritt definierte Umgebungsvariable die Auftrags- und Workflow-Variablen mit dem gleichen Namen überschreiben, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Variable überschreibt die Workflow-Variable mit dem gleichen Namen, während der Auftrag ausgeführt wird.

Die erwarteten Umgebungsvariablen können durch öffentliche Aktionen in der README-Datei angegeben werden. Wenn Du ein Geheimnis in einer Umgebungsvariable festlegst, musst Du dieses Geheimnis mit dem Kontext secrets angeben. Weitere Informationen findest Du unter „Umgebungsvariablen verwenden“ und „Kontext- und Ausdruckssyntax für GitHub Actions“.

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. Leg true fest, damit ein Auftrag auch dann erfolgreich abgeschlossen werden kann, wenn dieser Schritt fehlschlägt.

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

jobs.<job_id>.strategy

Mit einer Strategie wird eine Build-Matrix für die Aufträge erstellt. You can define different variations to run each job in.

jobs.<job_id>.strategy.matrix

Du kannst eine Matrix aus verschiedenen Job-Konfigurationen definieren. Mit einer Matrix kannst Du mehrere Jobs erstellen, indem Du in einer einzigen Jobdefinition Variablen substituierst. Zum Beispiel kannst Du eine Matrix verwenden, um Jobs für mehrere unterstützte Versionen einer Programmiersprache, eines Betriebssystems oder eines Tools zu erstellen. Eine Matrix verwendet die Job-Konfiguration mehrfach und erstellt einen Job für jeden Eintrag in der Matrix, die Du konfigurierst.

Eine Auftragsmatrix kann maximal 256 Aufträge pro Workflow-Ausführung generieren. Dieses Limit gilt auch für selbst-gehostete Läufer.

Jede Option, die Du in der Matrix definierst, hat einen Schlüssel und einen Wert. Die Schlüssel, die Du definierst, werden zu Eigenschaften im Kontext Matrix und Du kannst diese Eigenschaften in anderen Bereichen Ihrer Workflow-Datei referenzieren. Wenn Du zum Beispiel den Schlüssel os definierst, der ein Array von Betriebssystemen enthält, kannst Du die Eigenschaft matrix.os als Wert für das Schlüsselwort runs-on verwenden, um einen Job für jedes Betriebssystem zu erstellen. Weitere Informationen findest Du unter „Kontext- und Ausdrucks-Syntax für GitHub Actions“.

Die Reihenfolge, in der Du eine Matrix definierst, ist wichtig. Die erste Option, die Du definierst, ist der erste Job, der im Workflow ausgeführt wird.

Example: Running multiple versions of Node.js

Zum Erstellen einer Matrix geben Sie ein Array für die Konfigurationsoptionen an. Wenn der Runner beispielsweise die Node.js-Versionen 10, 12 und 14 unterstützt, kannst Du ein Array dieser Versionen in der matrix festlegen.

Dieses Beispiel erzeugt eine Matrix von drei Jobs, indem der Schlüssel node auf ein Array von drei Node.js-Versionen gesetzt wird. Um die Matrix zu verwenden, setzt das Beispiel die Kontexteigenschaft matrix.node als Wert des Eingabeparameters node-version der Aktion setup-node. Daher werden drei Jobs ausgeführt, die jeweils eine andere Version von Node.js verwenden.

strategy:
  matrix:
    node: [10, 12, 14]
steps:
  # Configures the node version used on GitHub-hosted runners
  - uses: actions/setup-node@v2
    with:
      # The Node.js version to configure
      node-version: ${{ matrix.node }}

Die Aktion setup-node ist das empfohlene Mittel zur Konfiguration einer Node.js-Version, wenn GitHub-gehostete Runner verwendet werden. Weitere Informationen findest Du in der Aktion setup-node.

Example: Running with multiple operating systems

Du kannst eine Matrix erstellen, um Workflows auf mehreren Runner-Betriebssystemen auszuführen. Du kannst auch mehrere Matrix-Konfigurationen angeben. Dieses Beispiel erstellt eine Matrix von 6 Jobs:

  • 2 Betriebssysteme im Array os angegeben
  • 3 Node.js Versionen im Array node angegeben

Wenn Du eine Matrix von Betriebssystemen definierst, musst Du den Wert runs-on (läuft auf) auf die von Dir definierte Kontexteigenschaft matrix.os setzen.

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

To find supported configuration options for GitHub-hosted runners, see "Virtual environments for GitHub-hosted runners."

Example: Including additional values into combinations

Zu einem bereits vorhandenen Job mit Buildmatrix kannst Du weitere Konfigurationsoptionen hinzufügen. Wenn Du beispielsweise eine bestimmte Version von npm verwenden willst, wenn der Auftrag mit windows-latest und Version 8 von node ausgeführt wird, kannst Du include verwenden, um diese zusätzliche Option anzugeben.

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [8, 10, 12, 14]
    include:
      # includes a new variable of npm with a value of 6
      # for the matrix leg matching the os and version
      - os: windows-latest
        node: 8
        npm: 6

Example: Including new combinations

Du kannst include verwenden, um neue Jobs zu einer Build-Matrix hinzuzufügen. Alle Include-Konfigurationen, die nicht passen, werden zur Matrix hinzugefügt. Wenn Du beispielsweise node Version 14 verwenden willst, um auf mehreren Betriebssystemen zu bauen, aber Du willst einen zusätzlichen experimentellen Job mit Node Version 15 auf Ubuntu, kannst Du include verwenden, um diesen zusätzlichen Job anzugeben.

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    node: [14]
    os: [macos-latest, windows-latest, ubuntu-18.04]
    include:
      - node: 15
        os: ubuntu-18.04
        experimental: true

Example: Excluding configurations from a matrix

Mit der Option exclude kannst Du bestimmte in der Build-Matrix definierte Konfigurationen entfernen. Durch die Verwendung von exclude wird ein durch die Build-Matrix definierter Job entfernt. Die Anzahl der Jobs ist das Kreuzprodukt der Anzahl der Betriebssysteme (os), die in den von Dir bereitgestellten Arrays enthalten sind, abzüglich etwaiger Subtraktionen (exclude).

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [8, 10, 12, 14]
    exclude:
      # excludes node 8 on macOS
      - os: macos-latest
        node: 8

Hinweis: Alle Kombinationen von include werden nach exclude verarbeitet. So kannst Du zuvor ausgeschlossene Kombinationen mit include wieder hinzufügen.

Using environment variables in a matrix

You can add custom environment variables for each test combination by using the include key. You can then refer to the custom environment variables in a later step.

In this example, the matrix entries for node-version are each configured to use different values for the site and datacenter environment variables. The Echo site details step then uses env: ${{ matrix.env }} to refer to the custom variables:

name: Node.js CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
       include:
         - node-version: 10.x
           site: "prod"
           datacenter: "site-a"
         - node-version: 12.x
           site: "dev"
           datacenter: "site-b"
    steps:
      - name: Echo site details
        env:
          SITE: ${{ matrix.site }}
          DATACENTER: ${{ matrix.datacenter }}
        run: echo $SITE $DATACENTER

jobs.<job_id>.strategy.fail-fast

Wenn diese Option auf true gesetzt ist, bricht GitHub alle laufenden Aufträge ab, sobald ein matrix-Auftrag fehlschlägt. Standard: true

jobs.<job_id>.strategy.max-parallel

Maximale Anzahl der Aufträge, die gleichzeitig ausgeführt werden können, wenn eine matrix-Auftragsstrategie herangezogen wird. Standardmäßig führt GitHub so viele Aufträge wie möglich parallel aus, je nach der Anzahl der verfügbaren Runner auf von GitHub gehosteten virtuellen Maschinen.

strategy:
  max-parallel: 2

jobs.<job_id>.continue-on-error

Verhindert, dass ein Workflow scheitert, wenn ein Job scheitert. Setze es auf true um einen Workflow-Lauf fortzusetzen, wenn dieser Job scheitert.

Example: Preventing a specific failing matrix job from failing a workflow run

Du kannst zulassen, dass bestimmte Jobs in einer Jobmatrix scheitert, ohne dass der Workflow-Lauf scheitert. Das gilt beispielsweise, wenn Du nur einem experimentellen Job, bei dem node auf 15 gesetzt wurde, das Scheitern erlauben willst, ohne dass dadurch der Workflow-Lauf scheitert.

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

jobs.<job_id>.container

Container, in dem alle Schritte eines Auftrags ausgeführt werden, für die kein Container explizit angegeben ist. 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 Host ausgeführt, der mit runs-on angegeben ist, außer wenn ein Schritt auf eine Aktion verweist, die für die Ausführung in einem Container konfiguriert ist.

Beispiel

jobs:
  my_job:
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1

Wenn Sie nur ein Container-Image angeben, können Sie das Stichwort image weglassen.

jobs:
  my_job:
    container: node:14.16

jobs.<job_id>.container.image

Docker-Image, das beim Ausführen der Aktion als Container herangezogen wird. The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.container.credentials

If the image's container registry requires authentication to pull the image, you can use credentials to set a map of the username and password. The credentials are the same values that you would provide to the docker login command.

Beispiel

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

jobs.<job_id>.container.env

Legt eine map mit Umgebungsvariablen im Container fest.

jobs.<job_id>.container.ports

Legt ein array mit Ports fest, die im Container offengelegt werden.

jobs.<job_id>.container.volumes

Legt ein array mit Volumes für den Container fest. Mithilfe von Volumes können Sie Daten zwischen Diensten oder anderen Schritten in einem Auftrag austauschen. Sie können benannte Docker-Volumes, anonyme Docker-Volumes oder Bind-Mounts auf dem Host angegeben.

Für ein Volume geben Sie den Quell- und Zielpfad an:

<source>:<destinationPath>.

<source> bezeichnet einen Volume-Namen oder einen absoluten Pfad auf der Hostmaschine und <destinationPath> einen absoluten Pfad im Container.

Beispiel

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

jobs.<job_id>.container.options

Zusätzliche Optionen für die Docker-Containerressource. Eine Liste der Optionen finden Sie unter „Optionen für docker create“.

jobs.<job_id>.services

Hinweis: Wenn Deine Workflows Docker-Containeraktionen oder Dienstcontainer verwenden, musst Du einen Linux-Läufer verwenden:

  • If you are using GitHub-hosted runners, you must use an Ubuntu runner.
  • 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 Job so konfigurieren, dass er in einem Container läuft, oder wenn Dein Schritt Containeraktionen verwendet, brauchst Du keine Ports zuordnen, 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 des Labels zugeordnet, den Du für den Dienst im Workflow konfigurierst.

Wenn Du den Job so konfigurierst, dass er direkt auf der Runner-Maschine läuft und Dein Schritt keine Container-Aktion verwendet, musst Du alle erforderlichen Ports des Docker-Servicecontainers dem Docker-Host (der Runner-Maschine) zuordnen. Du kannst auf den Servicecontainer über localhost und den zugeordneten Port zugreifen.

Weitere Informationen über die Unterschiede zwischen Netzwerk-Servicecontainern finden Sie unter „Informationen zu Servicecontainern“.

Example: Using localhost

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 setzt den zugewiesenen Containerport im Kontext ${{job.services.<service_name>.ports}} . In diesem Beispiel kannst Du über die Kontexte ${{ job.services.nginx.ports['8080'] }} und ${{ job.services.redis.ports['6379'] }} auf die Ports des Servicecontainers zugreifen.

services:
  nginx:
    image: nginx
    # Port 8080 des Docker-Hosts dem Port 80 des nginx-Containers zuordnen
    ports:
      - 8080:80
  redis:
    image: redis
    # TCP-Port 6379 des Docker-Hosts einem freien Port des Redis-Containers zufällig zuordnen
    ports:
      - 6379/tcp

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

Docker-Image, das beim Ausführen der Aktion als Dienstcontainer herangezogen wird. The value can be the Docker Hub image name or a registry name.

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

If the image's container registry requires authentication to pull the image, you can use credentials to set a map of the username and password. The credentials are the same values that you would provide to the docker login command.

Beispiel

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

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

Legt eine map mit Umgebungsvariablen im Servicecontainer fest.

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

Legt ein array mit Ports fest, die im Dienstcontainer offengelegt werden.

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

Legt ein array mit Volumes für den Dienstcontainer fest. Mithilfe von Volumes können Sie Daten zwischen Diensten oder anderen Schritten in einem Auftrag austauschen. Sie können benannte Docker-Volumes, anonyme Docker-Volumes oder Bind-Mounts auf dem Host angegeben.

Für ein Volume geben Sie den Quell- und Zielpfad an:

<source>:<destinationPath>.

<source> bezeichnet einen Volume-Namen oder einen absoluten Pfad auf der Hostmaschine und <destinationPath> einen absoluten 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-Containerressource. Eine Liste der Optionen finden Sie unter „Optionen für docker create“.

Merkzettel zu Filtermustern

In Pfad-, Branch- und Tag-Filtern kannst Du Sonderzeichen benutzen.

  • *Steht für kein Zeichen oder mehrere Zeichen, nicht jedoch für den Schrägstrich (/). Zum Beispiel passt Okto* auf Oktocat.
  • **: Steht für kein Zeichen oder mehrere beliebige Zeichen.
  • ?: Steht für kein Zeichen oder ein einzelnes Zeichen. Zum Beispiel passt Oktoc?t auf Oktocat.
  • +: Matches one or more of the preceding character.
  • [] Steht für irgend ein Zeichen, das in den Klammern aufgelistet ist oder das in einen in den Klammern enthalten Bereich fällt. Mögliche Bereiche sind ausschließlich a-z, A-Z und 0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. Zum Beispiel passt [CB]at sowohl zu Cat als auch zu Bat und [1-2]00 passt sowohl zu 100 als auch zu 200.
  • !: Am Anfang eines Musters stehend negiert es das Muster in sein Gegenteil. Es hat keine besondere Bedeutung, wenn es nicht das erste Zeichen ist.

Die Zeichen *, [ und ! sind Sonderzeichen in YAML. Wenn ein Muster mit *, [ oder ! beginnen soll, schließe das Muster in Anführungszeichen ein.

# Gueltig
- '**/README.md'

# Ungueltig - verursacht einen Parserfehler,
# der verhindert, dass der Workflow laeuft.
- **/README.md

Weitere Informationen zur Syntax für Branch-, Tag- und Pfadfilter findest Du unter „on.<push|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 * steht für ein beliebiges Zeichen, nicht jedoch für den Schrägstrich (/).feature/my-branch

feature/your-branch
feature/**Das Platzhalterzeichen ** steht für ein beliebiges Zeichen, also auch für den Schrägstrich (/), in Branch- und Tag-Namen.feature/beta-a/my-branch

feature/your-branch

feature/mona/the/octocat
main

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

releases/mona-the-octocat
'*'Abgleich mit allen Branch- und Tag-Namen, die keinen Schrägstrich (/) enthalten. Das Zeichen * ist ein Sonderzeichen in YAML. Wenn ein Muster mit * beginnen soll, sind Anführungszeichen erforderlich.main

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

every/tag
'*feature'Das Zeichen * ist ein Sonderzeichen in YAML. Wenn ein Muster mit * beginnen soll, sind Anführungszeichen erforderlich.mona-feature

feature

ver-10-feature
v2*Abgleich mit Branch- und Tag-Namen, die mit v2 beginnen.v2

v2.0

v2.9
v[12].[0-9]+.[0-9]+Matches all semantic versioning branches and tags with major version 1 or 2v1.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 * steht für ein beliebiges Zeichen, nicht jedoch für den Schrägstrich (/). Das Zeichen * ist ein Sonderzeichen in YAML. Wenn ein Muster mit * beginnen soll, sind Anführungszeichen erforderlich.README.md

server.rb
'*.jsx?'Das Zeichen ? steht für null Instanzen oder genau eine Instanz des vorangegangenen Zeichens.page.js

page.jsx
'**'Das Platzhalterzeichen ** steht für ein beliebiges Zeichen, auch für den Schrägstrich (/). Dies ist das Standardverhalten, wenn Sie keinen path-Filter angeben.all/the/files.md
'*.js'Das Platzhalterzeichen * steht für ein beliebiges Zeichen, nicht jedoch für den Schrägstrich (/). Abgleich mit allen .js-Dateien im Root des Repositorys.app.js

index.js
'**.js'Abgleich mit allen .js-Dateien im Repository.index.js

js/index.js

src/js/app.js
docs/*Alle Dateien im Root des Verzeichnisses docs im Root des Repositorys.docs/README.md

docs/file.txt
docs/**Beliebige Dateien im Verzeichnis docs im Root des Repositorys.docs/README.md

docs/mona/octocat.txt
docs/**/*.mdEine Datei mit dem Suffix .md an beliebiger Stelle im Verzeichnis docs.docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md
'**/docs/**'Beliebige Dateien im Verzeichnis docs an beliebiger Stelle im Repository.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/**'Eine beliebige Datei in einem Ordner mit dem Suffix src an beliebiger Stelle im Repository.a/src/app.js

my-src/code/js/app.js
'**/*-post.md'Eine Datei mit dem Suffix -post.md an beliebiger Stelle im Repository.my-post.md

path/their-post.md
'**/migrate-*.sql'Eine Datei mit dem Präfix migrate- und dem Suffix .sql an beliebiger Stelle im Repository.migrate-10909.sql

db/migrate-v1.0.sql

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

!README.md
Ein Ausrufezeichen (!) vor einem Muster negiert das Muster. 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

Does not match

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

Did this doc help you?Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Oder, learn how to contribute.