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 des Workflows. GitHub zeigt die Namen deiner Workflows auf der Registerkarte „Aktionen“ deines Repositorys an. Wenn du name
weglässt, zeigt GitHub den Workflowdateipfad relativ zum Stammverzeichnis des Repositorys an.
run-name
Der vom Workflow aus generierte Name für Workflowausführungen. GitHub zeigt den Namen der Workflowausführung in der Liste der Workflowausführungen auf der Registerkarte „Aktionen“ deines Repositorys an. Wenn run-name
weggelassen wird oder nur aus Leerzeichen besteht, werden ereignisspezifische Informationen für die Workflowausführung für den Namen der Ausführung verwendet. Beispielsweise wird er für einen Workflow, der von einem push
- oder pull_request
-Ereignis ausgelöst wird, als Commitnachricht festgelegt.
Dieser Wert kann Ausdrücke enthalten und auf die Kontexte github
und inputs
verweisen.
Beispiel für run-name
run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}
on
Zum automatischen Auslösen eines Workflows definierst du mit on
, welche Ereignisse eine Ausführung des Workflows verursachen. Eine Liste der verfügbaren Ereignisse findest du unter Ereignisse zum Auslösen von Workflows.
Du kannst einzelne oder mehrere Ereignisse definieren, die einen Workflow auslösen können, oder einen Zeitplan festlegen. Du kannst auch die Ausführung eines Workflows auf bestimmte Dateien, Tags oder Branchänderungen beschränken. Diese Optionen sind in den folgenden Abschnitten beschrieben.
Verwenden eines einzelnen Ereignisses
Beispielsweise wird ein Workflow mit dem folgenden on
-Wert ausgeführt, wenn in einem beliebigen Branch im Repository des Workflows ein Push erfolgt:
on: push
Verwenden mehrerer Ereignisse
Du kannst ein einzelnes Ereignis oder mehrere Ereignisse angeben. Beispielsweise wird ein Workflow mit dem folgenden on
-Wert ausgeführt, wenn in einem beliebigen Branch im Repository des Workflows ein Push erfolgt oder wenn jemand ein Repository forkt:
on: [push, fork]
Wenn du mehrere Ereignisse angibst, muss nur eines dieser Ereignisse auftreten, um deinen Workflow auszulösen. Treten gleichzeitig mehrere auslösende Ereignisaktivitätstypen für deinen Workflow auf, werden mehrere Workflow-Ausführungen ausgelöst.
Verwenden von Aktivitätstypen
Einige Ereignisse verfügen über Aktivitätstypen, die dir mehr Kontrolle darüber geben, wann dein Workflow ausgeführt werden soll. Verwende on.<event_name>.types
, um die Art der Ereignisaktivität zu definieren, durch die eine Workflowausführung ausgelöst werden soll.
Das Ereignis issue_comment
verfügt beispielsweise über die Aktivitätstypen created
, edited
und deleted
. Wenn dein Workflow durch ein Ereignis vom Typ label
ausgelöst wird, wird es ausgeführt, wenn eine Bezeichnung erstellt, bearbeitet oder gelöscht wird. Wenn du den Aktivitätstyp created
für das Ereignis label
angibst, wird der Workflow ausgeführt, wenn eine Bezeichnung erstellt wird, aber nicht, wenn eine Bezeichnung bearbeitet oder gelöscht wird.
on:
label:
types:
- created
Bei Angabe mehrerer Aktivitätstypen wird dein Workflow ausgelöst, wenn einer dieser Ereignisaktivitätstypen auftritt. Treten gleichzeitig mehrere auslösende Ereignisaktivitätstypen für deinen Workflow auf, werden mehrere Workflowausführungen ausgelöst. Der folgende Workflow wird beispielsweise ausgelöst, wenn ein Issue erstellt oder beschriftet wird. Wenn ein Issue mit zwei Bezeichnungen erstellt wird, werden drei Workflowausführungen gestartet: eine für das Issue-Erstellungsereignis und zwei für die beiden Issue-Beschriftungsereignisse.
on:
issues:
types:
- opened
- labeled
Weitere Informationen zu den einzelnen Ereignissen und ihren Aktivitätstypen findest du unter Ereignisse zum Auslösen von Workflows.
Verwenden von Filtern
Einige Ereignisse verfügen über Filter, die Ihnen mehr Kontrolle darüber geben, wann Ihr Workflow ausgeführt werden soll.
Das push
-Ereignis verfügt beispielsweise über einen branches
-Filter. Dieser führt dazu, dass der Workflow nicht bei jedem beliebigen Push, sondern nur bei einem Push an einen Branch ausgeführt wird, der mit dem branches
-Filter übereinstimmt.
on:
push:
branches:
- main
- 'releases/**'
Verwenden von Aktivitätstypen und Filtern mit mehreren Ereignissen
Wenn du Aktivitätstypen oder Filter für ein Ereignis und deine Workflowauslöser für mehrere Ereignisse angibst, musst du jedes Ereignis separat konfigurieren. Du musst einen Doppelpunkt (:
) an alle Ereignisse anhängen, einschließlich Ereignisse ohne Konfiguration.
Beispielsweise wird ein Workflow mit dem folgenden on
-Wert ausgeführt, wenn:
- Eine Bezeichnung erstellt wird
- Ein Push an die
main
-Verzweigung im Repository vorgenommen wird - Ein Push an eine GitHub Pages-aktivierte Verzweigung vorgenommen wird
on:
label:
types:
- created
push:
branches:
- main
page_build:
on.<event_name>.types
Verwende on.<event_name>.types
zum Definieren des Aktivitätstyps, der eine Workflowausführung auslöst. Die meisten GitHub-Ereignisse werden von mehreren Aktivitätstypen ausgelöst. Beispielsweise wird label
ausgelöst, wenn für eine Bezeichnung eine der folgenden Aktivitäten durchgeführt wird: created
, edited
oder deleted
. Mit dem Schlüsselwort types
kannst du die Aktivitäten eingrenzen, durch die die Ausführung des Workflows ausgelöst wird. Wenn nur ein Aktivitätstyp ein Webhookereignis auslöst, ist das Schlüsselwort types
unnötig.
Du kannst ein Array von types
für Ereignisse verwenden. Weitere Informationen zu den einzelnen Ereignissen und ihren Aktivitätstypen findest du unter Ereignisse zum Auslösen von Workflows.
on:
label:
types: [created, edited]
on.<pull_request|pull_request_target>.<branches|branches-ignore>
Wenn Du die Ereignisse pull_request
und pull_request_target
verwendest, kannst Du einen Workflow konfigurieren, der nur für Pull Requests ausgeführt werden kann, die auf bestimmte Branches abzielen.
Verwende den Filter branches
, wenn Du Branchnamenmuster entweder einschließen oder ein- und ausschließen möchtest. Verwende den Filter branches-ignore
, wenn du Branchnamenmuster nur ausschließen möchtest. Du kannst die Filter branches
und branches-ignore
nicht für dasselbe Ereignis in einem Workflow nutzen.
Wenn du sowohl branches
/branches-ignore
als auch paths
/paths-ignore
definierst, wird der Workflow nur ausgeführt, wenn beide Filter zutreffen.
Die Schlüsselwörter branches
und branches-ignore
akzeptieren Globmuster, die die Platzhalterzeichen *
, **
, +
, ?
, !
verwenden, um zu mehr als einem Branchnamen zu passen. Wenn ein Name eines dieser Zeichen enthält und Du eine literale Übereinstimmung wünscht, musst Du jedes dieser Sonderzeichen mit \
als Escapezeichen verwenden. Weitere Informationen zu Globmustern findest du unter Workflowsyntax für GitHub Actions.
Beispiel: Einschließen von Branches
Die in branches
definierten Muster werden mit dem Namen des Git-Ref ausgewertet. Der folgende Workflow würde zum Beispiel immer dann ablaufen, wenn ein pull_request
-Ereignis für einen Pull Request vorliegt:
- Ein Branch namens
main
(refs/heads/main
) - Ein Branch namens
mona/octocat
(refs/heads/mona/octocat
) - Ein Branch, dessen Name mit
releases/
beginnt, wiereleases/10
(refs/heads/releases/10
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
Sie sollten keine Pfad- oder Branchfilterung verwenden, um Workflowausführungen zu überspringen, wenn der Workflow erforderlich ist. Weitere Informationen findest du unter Überspringen von Workflowausführungen und Erforderliche Workflows.
Wenn ein Workflow aufgrund einer Branchfilterung, Pfadfilterung oder Commitnachricht übersprungen wird, verbleiben diesem Workflow zugeordnete Überprüfungen im Status „Ausstehend“. Ein Pull Request, bei dem diese Prüfungen erfolgreich sein müssen, wird vom Mergen ausgeschlossen.
Beispiel: Ausschließen von Branches
Wenn ein Muster dem Muster branches-ignore
entspricht, wird der Workflow nicht ausgeführt. Die in branches-ignore
definierten Muster werden mit dem Namen des Git-Ref ausgewertet. Der folgende Arbeitsablauf würde zum Beispiel immer dann ablaufen, wenn ein pull_request
-Ereignis eintritt, es sei denn, der Pull Request ist zielgerichtet:
- Ein Branch namens
mona/octocat
(refs/heads/mona/octocat
) - Ein Branch, dessen Name mit
releases/**-alpha
übereinstimmt, wiereleases/beta/3-alpha
(refs/heads/releases/beta/3-alpha
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
Beispiel: Einschließen und Ausschließen von Branches
Du kannst dasselbe Ereignis nicht mit branches
und branches-ignore
in einem einzigen Workflow filtern. Wenn Du Branchmuster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchten, verwendest Du den Filter branches
zusammen mit dem Zeichen !
, um die auszuschließenden Branches anzugeben.
Wenn Du einen Branch mit dem Zeichen !
definierst, musst Du auch mindestens einen Branch ohne das Zeichen !
definieren. Wenn Du nur Branches ausschließen möchten, verwendest Du stattdessen branches-ignore
.
Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.
- Ein passendes negatives Muster (mit dem Präfix
!
) nach einer positiven Übereinstimmung schließt den Verweis auf Git aus. - Ein übereinstimmendes positives Muster nach einem negativen Abgleich schließt die Git-Ref wieder ein.
Der folgende Workflow wird bei pull_request
-Ereignissen für Pull Requests ausgeführt, die auf releases/10
oder releases/beta/mona
abzielen, aber nicht für Pull-Requests, die auf releases/10-alpha
oder releases/beta/3-alpha
abzielen, weil das negative Muster !releases/**-alpha
auf das positive Muster folgt.
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.push.<branches|tags|branches-ignore|tags-ignore>
Wenn du das push
-Ereignis verwendest, kannst du einen Workflow so konfigurieren, dass er auf bestimmten Branches oder Tags ausgeführt wird.
Verwende den Filter branches
, wenn du Branchnamenmuster entweder einschließen oder ein- und ausschließen möchtest. Verwende den Filter branches-ignore
, wenn du Branchnamenmuster nur ausschließen möchtest. Du kannst die Filter branches
und branches-ignore
nicht für dasselbe Ereignis in einem Workflow nutzen.
Verwende den Filter tags
, wenn du Tagnamenmuster entweder einschließen oder ein- und ausschließen möchtest. Verwende den Filter tags-ignore
, wenn du Tagnamenmuster nur ausschließen möchtest. Du kannst die Filter tags
und tags-ignore
nicht für dasselbe Ereignis in einem Workflow nutzen.
Wenn du nur tags
/tags-ignore
oder nur branches
/branches-ignore
definierst, wird der Workflow nicht für Ereignisse ausgeführt, die sich auf die nicht definierten Git-Verweise auswirken. Wenn du weder tags
/tags-ignore
noch branches
/branches-ignore
definierst, wird der Workflow für Ereignisse ausgeführt, die sich entweder auf Branches oder Tags auswirken. Wenn du sowohl branches
/branches-ignore
als auch paths
/paths-ignore
definierst, wird der Workflow nur ausgeführt, wenn beide Filter zutreffen.
Die Schlüsselwörter branches
, branches-ignore
, tags
und tags-ignore
akzeptieren Globmuster, die die Zeichen *
, **
, +
, ?
, !
etc. verwenden, um mehr als einem Branch- oder Tagnamen zu entsprechen. Wenn ein Name eines dieser Zeichen enthält und du eine genaue Übereinstimmung möchtest, musst du jedes dieser Sonderzeichen mit \
versehen. Weitere Informationen zu Globmustern findest du unter Workflowsyntax für GitHub Actions.
Beispiel: Einschließen von Branches und Tags
Die in branches
und tags
definierten Muster werden anhand des Namens des Git-Verweises ausgewertet. Der folgende Workflow wird beispielsweise jedes Mal ausgeführt, wenn ein push
-Ereignis an folgende Instanzen ausgeführt wird:
- Ein Branch namens
main
(refs/heads/main
) - Ein Branch namens
mona/octocat
(refs/heads/mona/octocat
) - Ein Branch, dessen Name mit
releases/
beginnt, wiereleases/10
(refs/heads/releases/10
) - Ein Tag namens
v2
(refs/tags/v2
) - Ein Tag, dessen Name mit
v1.
beginnt, wiev1.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, wiereleases/beta/3-alpha
(refs/heads/releases/beta/3-alpha
) - Ein Tag namens
v2
(refs/tags/v2
) - Ein Tag, dessen Name mit
v1.
beginnt, wiev1.9
(refs/tags/v1.9
)
on:
push:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
# Sequence of patterns matched against refs/tags
tags-ignore:
- v2
- v1.*
Beispiel: Einschließen und Ausschließen von Branches und Tags
Du kannst branches
und branches-ignore
nicht verwenden, um dasselbe Ereignis in einem einzigen Workflow zu filtern. Ebenso kannst du tags
und tags-ignore
nicht verwenden, um dasselbe Ereignis in einem einzigen Workflow zu filtern. Wenn du Branch- oder Tagmuster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchtest, verwende den Filter branches
oder tags
zusammen mit dem Zeichen !
, um die auszuschließenden Branches und Tags anzugeben.
Wenn du einen Branch mit dem Zeichen !
definierst, musst du auch mindestens einen Branch ohne das Zeichen !
definieren. Wenn du nur Branches ausschließen möchtest, verwende stattdessen branches-ignore
. Wenn du ebenfalls einen Tag mit dem Zeichen !
definierst, musst du auch mindestens einen Tag ohne das Zeichen !
definieren. Wenn du nur Tags ausschließen möchtest, verwende stattdessen tags-ignore
.
Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.
- Ein passendes negatives Muster (mit dem Präfix
!
) nach einer positiven Übereinstimmung schließt den Verweis auf Git aus. - Ein übereinstimmendes positives Muster nach einem negativen Abgleich schließt die Git-Ref wieder ein.
Der folgenden Workflow führt Pushes an releases/10
oder releases/beta/mona
aus, aber nicht an releases/10-alpha
oder releases/beta/3-alpha
, da das negative Muster !releases/**-alpha
dem positiven Muster folgt.
on:
push:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.<push|pull_request|pull_request_target>.<paths|paths-ignore>
Wenn du die Ereignisse push
und pull_request
verwendest, kannst du einen Workflow konfigurieren, der basierend auf den geänderten Dateipfaden ausgeführt wird. Bei Push-Vorgängen zu Tags werden Pfadfilter nicht ausgewertet.
Verwende den Filter paths
, wenn du Dateipfadmuster entweder einschließen oder einschließen und ausschließen möchtest. Verwende den Filter paths-ignore
, wenn du Dateipfadmuster nur ausschließen möchtest. Du kannst die Filter paths
und paths-ignore
nicht für dasselbe Ereignis in einem Workflow nutzen. Wenn Pfadmuster für ein einzelnes Ereignis sowohl eingeschlossen als auch ausgeschlossen werden sollen, benutzen Sie den Filter paths
mit dem vorangestellten Zeichen !
, um die auszuschließenden Pfade anzugeben.
Hinweis: Die Reihenfolge, in der paths
-Muster definiert werden, ist entscheidend:
- Ein passendes negatives Muster mit dem Präfix
!
nach einem positiven Abgleich schließt den Pfad aus. - Ein passendes positives Muster nach einem negativen Abgleich schließt den Pfad wieder ein.
Wenn du sowohl branches
/branches-ignore
als auch paths
/paths-ignore
definierst, wird der Workflow nur ausgeführt, wenn beide Filter zutreffen.
Die Schlüsselwörter paths
und paths-ignore
akzeptieren Globmuster, die die Platzhalterzeichen *
und **
verwenden, um zu mehr als einem Pfadnamen zu passen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.
Beispiel: Einschließen von Pfaden
Wenn mindestens ein Pfad zu einem Muster im Filter paths
passt, wird der Workflow ausgeführt. Der folgende Workflow wird beispielsweise jedes Mal ausgeführt, wenn du eine JavaScript-Datei (.js
) pushst.
on:
push:
paths:
- '**.js'
Sie sollten keine Pfad- oder Branchfilterung verwenden, um Workflowausführungen zu überspringen, wenn der Workflow erforderlich ist. Weitere Informationen findest du unter Überspringen von Workflowausführungen und Erforderliche Workflows.
Wenn ein Workflow aufgrund von Pfadfilterung, Branchfilterung oder einer Commitnachricht übersprungen wird, verbleiben diesem Workflow zugeordnete Überprüfungen im Status „Ausstehend“. Ein Pull Request, bei dem diese Prüfungen erfolgreich sein müssen, wird vom Mergen ausgeschlossen.
Beispiel: Ausschließen von Pfaden
Wenn alle Pfadnamen mit Mustern in paths-ignore
übereinstimmen, wird der Workflow nicht ausgeführt. Wenn manche Pfadnamen nicht mit Mustern in paths-ignore
übereinstimmen, wird der Workflow ausgeführt, obwohl einige Pfadnamen den Mustern entsprechen.
Ein Workflow mit dem folgenden Pfadfilter wird nur bei push
-Ereignissen ausgeführt, bei denen sich mindestens eine Datei außerhalb des Verzeichnisses docs
im Stamm des Repositorys befindet.
on:
push:
paths-ignore:
- 'docs/**'
Beispiel: Einschließen und Ausschließen von Pfaden
Du kannst dasselbe Ereignis nicht mit paths
und paths-ignore
in einem einzigen Workflow filtern. Wenn Pfadmuster für ein einzelnes Ereignis sowohl eingeschlossen als auch ausgeschlossen werden sollen, benutzen Sie den Filter paths
mit dem vorangestellten Zeichen !
, um die auszuschließenden Pfade anzugeben.
Wenn du einen Pfad mit dem Zeichen !
definierst, musst du auch mindestens einen Pfad ohne das Zeichen !
definieren. Wenn du nur Pfade ausschließen möchtest, verwende stattdessen paths-ignore
.
Die Reihenfolge, in der paths
-Muster definiert werden, ist entscheidend:
- Ein passendes negatives Muster mit dem Präfix
!
nach einem positiven Abgleich schließt den Pfad aus. - Ein passendes positives Muster nach einem negativen Abgleich schließt den Pfad wieder ein.
In diesem Beispiel wird jedes Mal ausgeführt, wenn das Ereignis push
eine Datei im Verzeichnis sub-project
oder in seinen Unterverzeichnissen enthält, es sei denn, die Datei befindet sich im Verzeichnis sub-project/docs
. Beispielsweise löst in Push, der sub-project/index.js
oder sub-project/src/index.js
geändert hat, die Ausführung eines Workflows aus, dies geschieht jedoch nicht, wenn nur sub-project/docs/readme.md
geändert wurde.
on:
push:
paths:
- 'sub-project/**'
- '!sub-project/docs/**'
Git-Diff-Vergleiche
Hinweis: Wenn der Push-Vorgang mehr als 1.000 Commits umfasst oder wenn GitHub die Diff wegen einer Zeitüberschreitung nicht erzeugt, wird der Workflow immer ausgeführt.
Um zu ermitteln, ob ein Workflow ausgeführt werden soll, wertet der Filter die geänderten Dateien anhand der Listen paths-ignore
oder paths
aus. Wurden keine Dateien geändert, wird der Workflow nicht ausgeführt.
GitHub erzeugt die Liste der geänderten Dateien mithilfe von „Two-Dot-Diffs“ (Vergleiche mittels 2 Punkt-Syntax „..“) für Push-Vorgänge und „Three-Dot-Diffs“ (Vergleiche mittels 3 Punkt-Syntax „...“) für Pull-Requests:
- Pull Requests: Three-Dot-Diffs ziehen den Vergleich zwischen der neuesten Version des Topic-Branch und des Commit, bei dem der Topic-Branch zuletzt mit dem Basis-Branch synchronisiert wurde.
- Push-Vorgänge an bestehende Branches: Eine Two-Dot-Diff vergleicht die Head- und Basis-SHAs direkt miteinander.
- Push-Vorgänge an neue Branches: Eine Two-Dot-Diff wird zum übergeordneten Element des Vorgängers des tiefsten Commits gepusht.
Diffs sind auf 300 Dateien beschränkt. Wenn Dateien geändert werden, die nicht mit den ersten 300 vom Filter zurückgegebenen Dateien übereinstimmen, wird der Workflow nicht ausgeführt. Du musst eventuell genauere Filter erstellen, damit der Workflow automatisch ausgeführt wird.
Weitere Informationen findest du unter Informationen zum Vergleich von Branches in Pull Requests.
on.schedule
Mithilfe von on.schedule
kannst du einen Zeitplan für deine Workflows definieren. Mithilfe der POSIX-Cron-Syntax kannst du einen Workflow so planen, dass er zu bestimmten UTC-Zeiten ausgeführt wird. Geplante Workflows laufen auf dem jüngsten Commit auf dem Standard- oder Basisbranch. Das kürzeste Intervall, in dem Du geplante Workflows ausführen kannst, ist einmal alle 5 Minuten.
In diesem Beispiel wird der Workflow jeden Tag um 5:30 Uhr und 17:30 Uhr UTC ausgelöst:
on:
schedule:
# * is a special character in YAML so you have to quote this string
- cron: '30 5,17 * * *'
Ein einzelner Workflow kann durch mehrere schedule
-Ereignisse ausgelöst werden. Über den Kontext github.event.schedule
kannst du auf das Zeitplanereignis zugreifen, das den Workflow ausgelöst hat. In diesem Beispiel wird der Workflow von Montag bis Donnerstag um 5:30 Uhr UTC gestartet, wobei der Schritt Not on Monday or Wednesday
am Montag und Mittwoch übersprungen wird.
on:
schedule:
- cron: '30 5 * * 1,3'
- cron: '30 5 * * 2,4'
jobs:
test_schedule:
runs-on: ubuntu-latest
steps:
- name: Not on Monday or Wednesday
if: github.event.schedule != '30 5 * * 1,3'
run: echo "This step will be skipped on Monday and Wednesday"
- name: Every time
run: echo "This step will always run"
Weitere Informationen zur Cron-Syntax findest du unter Ereignisse zum Auslösen von Workflows.
on.workflow_call
Verwende on.workflow_call
, um die Eingaben und Ausgaben für einen wiederverwendbaren Workflow zu definieren. Du kannst dem aufgerufenen Workflow auch die verfügbaren Geheimnisse zuordnen. Weitere Informationen zu wiederverwendbaren Workflows findest du unter Wiederverwenden von Workflows.
on.workflow_call.inputs
Wenn du das Schlüsselwort workflow_call
verwendest, kannst du optional Eingaben angeben, die vom Aufruferworkflow an den aufgerufenen Workflow übergeben werden. Weitere Informationen zum Schlüsselwort workflow_call
findest du unter Ereignisse zum Auslösen von Workflows.
Zusätzlich zu den verfügbaren Standardeingabeparametern erfordert on.workflow_call.inputs
auch einen type
-Parameter. Weitere Informationen findest du unter on.workflow_call.inputs.<input_id>.type
.
Wenn kein default
-Parameter festgelegt ist, entspricht der Standardwert der Eingabe false
für einen booleschen Wert, 0
für eine Zahl und ""
für eine Zeichenfolge.
Innerhalb des aufgerufenen Workflows kannst du den inputs
-Kontext verwenden, um auf eine Eingabe zu verweisen. Weitere Informationen findest du unter Kontexte.
Wenn ein Aufruferworkflow eine Eingabe übergibt, die nicht im aufgerufenen Workflow angegeben ist, führt dies zu einem Fehler.
Beispiel für on.workflow_call.inputs
on:
workflow_call:
inputs:
username:
description: 'A username passed from the caller workflow'
default: 'john-doe'
required: false
type: string
jobs:
print-username:
runs-on: ubuntu-latest
steps:
- name: Print the input name to STDOUT
run: echo The username is ${{ inputs.username }}
Weitere Informationen findest du unter Wiederverwenden von Workflows.
on.workflow_call.inputs.<input_id>.type
Diese Angabe ist erforderlich, wenn die Eingabe für das Schlüsselwort on.workflow_call
definiert ist. Der Wert dieses Parameters ist eine Zeichenfolge, die den Datentyp der Eingabe angibt. Dies muss boolean
, number
oder string
entsprechen.
on.workflow_call.outputs
Hierbei handelt es sich um eine Zuordnung der Ausgaben für einen aufgerufenen Workflow. Die Ausgaben des aufgerufenen Workflows sind für alle Downstreamaufträge im Aufruferworkflow verfügbar. Jede Ausgabe verfügt über einen Bezeichner, eine optionale description,
und einen value.
. Der value
muss auf den Wert einer Ausgabe aus einem Auftrag innerhalb des aufgerufenen Workflows festgelegt werden.
Im folgenden Beispiel werden zwei Ausgaben für diesen wiederverwendbaren Workflow definiert: workflow_output1
und workflow_output2
. Diese werden den Ausgaben namens job_output1
und job_output2
zugeordnet, die beide von einem Auftrag namens my_job
stammen.
Beispiel für on.workflow_call.outputs
on:
workflow_call:
# Map the workflow outputs to job outputs
outputs:
workflow_output1:
description: "The first job output"
value: ${{ jobs.my_job.outputs.job_output1 }}
workflow_output2:
description: "The second job output"
value: ${{ jobs.my_job.outputs.job_output2 }}
Weitere Informationen zum Verweisen auf eine Auftragsausgabe findest du unter jobs.<job_id>.outputs
. Weitere Informationen findest du unter Wiederverwenden von Workflows.
on.workflow_call.secrets
Dies ist eine Zuordnung der Geheimnisse, die im aufgerufenen Workflow verwendet werden können.
Innerhalb des aufgerufenen Workflows kannst du den secrets
-Kontext verwenden, um auf ein Geheimnis zu verweisen.
Hinweis: Wenn du das Geheimnis an einen geschachtelten wiederverwendbaren Workflow übergibst, musst du jobs.<job_id>.secrets
erneut verwenden, um das Geheimnis zu übergeben. Weitere Informationen findest du unter Wiederverwenden von Workflows.
Wenn ein Aufruferworkflow ein Geheimnis übergibt, das nicht im aufgerufenen Workflow angegeben ist, führt dies zu einem Fehler.
Beispiel für on.workflow_call.secrets
on:
workflow_call:
secrets:
access-token:
description: 'A token passed from the caller workflow'
required: false
jobs:
pass-secret-to-action:
runs-on: ubuntu-latest
steps:
# passing the secret to an action
- name: Pass the received secret to an action
uses: ./.github/actions/my-action
with:
token: ${{ secrets.access-token }}
# passing the secret to a nested reusable workflow
pass-secret-to-workflow:
uses: ./.github/workflows/my-workflow
secrets:
token: ${{ secrets.access-token }}
on.workflow_call.secrets.<secret_id>
Dies ist ein Zeichenfolgenbezeichner, der dem Geheimnis zugeordnet werden soll.
on.workflow_call.secrets.<secret_id>.required
Dies ist ein boolescher Wert, der angibt, ob das Geheimnis angegeben werden muss.
on.workflow_run.<branches|branches-ignore>
Wenn du das workflow_run
-Ereignis verwendest, kannst du angeben, in welchen Branches der auslösende Workflow ausgeführt werden muss, um deinen Workflow auszulösen.
Die Filter branches
und branches-ignore
akzeptieren Globmuster, die die Platzhalterzeichen *
, **
, +
, ?
, !
und andere verwenden, um zu mehr als einem Branch-Namen zu passen. Wenn ein Name eines dieser Zeichen enthält und du eine literale Übereinstimmung wünscht, musst du für jedes dieser Sonderzeichen mit Escape mit \
verwenden. Weitere Informationen zu Globmustern findest du unter Workflowsyntax für GitHub Actions.
Beispielsweise wird ein Workflow mit dem folgenden Trigger nur ausgeführt, wenn der Workflow namens Build
in einem Branch namens releases/
ausgeführt wird.
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
Beispielsweise wird ein Workflow mit dem folgenden Trigger nur ausgeführt, wenn der Workflow namens Build
in einem Branch namens canary
ausgeführt wird:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
Du kannst die Filter branches
und branches-ignore
nicht für dasselbe Ereignis in einem Workflow nutzen. Wenn du Branch-Muster für ein einzelnes Ereignis sowohl einschließen als auch ausschließen möchtest, verwende den branches
-Filter zusammen mit dem !
-Zeichen, um die auszuschließenden Branches anzugeben.
Die Reihenfolge, in der Du die Muster definierst, ist entscheidend.
- Ein passendes negatives Muster (Präfix
!
) nach einem positiven Abgleich schließt die Branch aus. - Ein passendes positives Muster nach einem negativen Abgleich schließt die Branch wieder ein.
Beispielsweise wird ein Workflow mit dem folgenden Trigger nur ausgeführt, wenn der Workflow namens Build
in einem Branch namens releases/10
oder releases/beta/mona
, aber nicht releases/10-alpha
, releases/beta/3-alpha
oder main
ausgeführt wird.
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
on.workflow_dispatch
Bei Verwendung des workflow_dispatch
-Ereignisses kannst du optional Eingaben angeben, die an den Workflow übergeben werden.
Dieser Trigger empfängt nur Ereignisse, wenn sich die Workflow-Datei auf dem Standardbranch befindet.
on.workflow_dispatch.inputs
Der ausgelöste Workflow empfängt die Eingaben im inputs
-Kontext. Weitere Informationen findest du unter Kontexte.
Hinweise:
- Der Workflow empfängt auch die Eingaben im
github.event.inputs
-Kontext. Die Informationen im Kontextinputs
undgithub.event.inputs
sind identisch, außer dass der Kontextinputs
boolesche Werte als solche beibehält, anstatt sie in Zeichenfolgen zu konvertieren. Der Typchoice
wird in eine Zeichenfolge aufgelöst und ist eine einzelne auswählbare Option. - Die maximale Anzahl von Eigenschaften auf oberster Ebene für
inputs
beträgt 10. - Die maximale Länge der Nutzdaten für
inputs
beträgt 65.535 Zeichen.
Beispiel für on.workflow_dispatch.inputs
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
type: choice
options:
- info
- warning
- debug
print_tags:
description: 'True to print to STDOUT'
required: true
type: boolean
tags:
description: 'Test scenario tags'
required: true
type: string
environment:
description: 'Environment to run tests against'
type: environment
required: true
jobs:
print-tag:
runs-on: ubuntu-latest
if: ${{ inputs.print_tags }}
steps:
- name: Print the input tag to STDOUT
run: echo The tags are ${{ inputs.tags }}
on.workflow_dispatch.inputs.<input_id>.required
Dies ist ein boolescher Wert, der angibt, ob die Eingabe angegeben werden muss.
on.workflow_dispatch.inputs.<input_id>.type
Der Wert dieses Parameters ist eine Zeichenfolge, die den Datentyp der Eingabe angibt. Dieser muss boolean
, choice
, number
, environment
oder string
entsprechen.
permissions
Du kannst permissions
verwenden, um die Standardberechtigungen zu ändern, die dem GitHub-Token (GITHUB_TOKEN
) gewährt werden. So kannst du Zugriff nach Bedarf hinzufügen oder entfernen, um nur den mindestens erforderlichen Zugriff zu gewähren. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.
permissions
kann entweder als Schlüssel auf oberster Ebene verwendet werden, um für alle Aufträge im Workflow zu gelten, oder innerhalb bestimmter Aufträge. Wenn du den Schlüssel permissions
innerhalb eines bestimmten Auftrags hinzufügst, werden die von dir angegebenen Zugriffsrechte auf alle Aktionen und Ausführungsbefehle innerhalb dieses Auftrags angewendet, die das GitHub-Token (GITHUB_TOKEN
) verwenden. Weitere Informationen findest du unter jobs.<job_id>.permissions
.
Für jeden der verfügbaren Bereiche, die in der folgenden Tabelle dargestellt sind, kannst du eine der Berechtigungen zuweisen: read
, write
oder none
. Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none
festgelegt.
Verfügbare Bereiche und Einzelheiten dazu, was sie einer Aktion jeweils erlauben:
Scope | Erlaubt einer Aktion die Verwendung von GITHUB_TOKEN zum |
---|---|
actions | Arbeiten mit GitHub Actions. actions: write ermöglicht einer Aktion beispielsweise das Abbrechen einer Workflowausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
checks | Arbeiten mit Überprüfungsausführungen und Überprüfungssammlungen. checks: write ermöglicht einer Aktion beispielsweise das Erstellen einer Überprüfungsausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
contents | Arbeiten mit den Inhalten des Repositorys. contents: read ermöglicht einer Aktion beispielsweise das Auflisten der Commits, und contents:write ermöglicht der Aktion das Erstellen eines Releases. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
deployments | Arbeiten mit Bereitstellungen. deployments: write ermöglicht einer Aktion beispielsweise das Erstellen einer neuen Bereitstellung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
discussions | Arbeiten mit GitHub Discussions. discussions: write ermöglicht einer Aktion beispielsweise das Schließen oder Löschen einer Diskussion. Weitere Informationen findest du unter Verwenden der GraphQL-API für Diskussionen. |
issues | Arbeiten mit Issues. issues: write ermöglicht einer Aktion beispielsweise das Hinzufügen eines Kommentars zu einem Issue. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
packages | Arbeiten mit GitHub Packages. packages: write ermöglicht einer Aktion beispielsweise das Hochladen und Veröffentlichen von Paketen auf GitHub Packages. Weitere Informationen findest du unter Informationen zu Berechtigungen für GitHub-Pakete. |
pages | Arbeiten mit GitHub Pages. pages: write ermöglicht einer Aktion beispielsweise das Anfordern eines GitHub Pages-Builds. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
pull-requests | Arbeiten mit Pull Requests. pull-requests: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Bezeichnung zu einem Pull Request. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
repository-projects | Arbeiten mit GitHub-Projekten (klassisch). repository-projects: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Spalte zu einem Projekt (klassisch). Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
security-events | Arbeiten mit GitHub-Codeüberprüfungen und Dependabot-Warnungen. security-events: read ermöglicht einer Aktion beispielsweise das Auflisten der Dependabot-Warnungen für das Repository, und security-events: write ermöglicht einer Aktion, den Status einer Codeüberprüfungswarnung zu aktualisieren. Weitere Informationen findest du unter Repositoryberechtigungen für „Codeüberprüfungswarnungen“ und Repositoryberechtigungen für „Dependabot-Warnungen“ in „Für GitHub Apps erforderliche Berechtigungen“. |
statuses | Arbeiten mit Commitstatus. statuses:read ermöglicht einer Aktion beispielsweise das Auflisten der Commitstatus für einen bestimmten Verweis. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
Definieren des Zugriffs für die GITHUB_TOKEN
-Bereiche
Du kannst den Zugriff definieren, den das GITHUB_TOKEN
zulässt, indem du read
, write
oder none
als Wert der verfügbaren Bereiche innerhalb des permissions
-Schlüssels angibst.
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none
festgelegt.
Du kannst die folgende Syntax verwenden, um einen der read-all
- oder write-all
-Zugriffe für alle verfügbaren Reservierungsumfänge zu definieren:
permissions: read-all
permissions: write-all
Du kannst die folgende Syntax verwenden, um Berechtigungen für alle verfügbaren Bereiche zu deaktivieren:
permissions: {}
Ändern der Berechtigungen in einem geforkten Repository
Darüber hinaus kannst du den permissions
-Schlüssel verwenden, um Leseberechtigungen für geforkte Repositorys hinzuzufügen oder zu entfernen, aber in der Regel kannst du keinen Schreibzugriff gewähren. Eine Ausnahme für dieses Verhalten besteht dann, wenn ein Administratorbenutzer die Option Schreibtoken an Workflows aus Pull Requests senden in den GitHub Actions-Einstellungen ausgewählt hat. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.
Festlegen der GITHUB_TOKEN
-Berechtigungen für alle Aufträge in einem Workflow
Du kannst permissions
auf der obersten Ebene eines Workflows angeben, sodass die Einstellung für alle Aufträge im Workflow gilt.
Beispiel: Festlegen der GITHUB_TOKEN
-Berechtigungen für einen gesamten Workflow
In diesem Beispiel wird gezeigt, wie Berechtigungen für das GitHub-Token (GITHUB_TOKEN
) festgelegt werden, die für alle Aufträge im Workflow gelten. Bei allen Berechtigungen handelt es sich um die Gewährung von Lesezugriff.
name: "My workflow"
on: [ push ]
permissions: read-all
jobs:
...
env
Dies ist eine map
von Variablen, die für die Schritte aller Aufträge im Workflow verfügbar sind. Du kannst auch Variablen festlegen, die nur für die Schritte eines einzelnen Auftrags oder für einen einzelnen Schritt verfügbar sind. Weitere Informationen findest du unter jobs.<job_id>.env
und jobs.<job_id>.steps[*].env
.
Variablen in der env
-Zuordnung können nicht in Bezug auf andere Variablen in der Zuordnung definiert werden.
Wenn mehr als eine Umgebungsvariable mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Variable. Beispielsweise setzt eine in einem Schritt definierte Umgebungsvariable Auftrags- und Workflowumgebungsvariablen mit demselben Namen außer Kraft, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Umgebungsvariable setzt eine Workflowvariable mit demselben Namen außer Kraft, während der Auftrag ausgeführt wird.
Beispiel für env
env:
SERVER: production
defaults
Verwende defaults
, um eine map
der Standardeinstellungen zu erstellen, die für alle Aufträge im Workflow gelten. Du kannst auch Standardeinstellungen festlegen, die nur für einen Job verfügbar sind. Weitere Informationen findest du unter jobs.<job_id>.defaults
.
Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.
defaults.run
Du kannst defaults.run
verwenden, um Standardoptionen für shell
und working-directory
für alle run
-Schritte in einem Workflow bereitzustellen. Du kannst auch Standardeinstellungen für run
festlegen, die nur für einen Auftrag verfügbar sind. Weitere Informationen findest du unter jobs.<job_id>.defaults.run
. In diesem Schlüsselwort kannst Du keine Kontexte oder Ausdrücke verwenden.
Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.
Beispiel: Festlegen der Standardshell und des Arbeitsverzeichnisses
defaults:
run:
shell: bash
working-directory: ./scripts
defaults.run.shell
Nutzen von shell
zum Definieren von shell
eines Schritts. Dieses Schlüsselwort kann auf mehrere Kontexte verweisen. Weitere Informationen findest du unter Kontexte.
Unterstützte Plattform | shell -Parameter | BESCHREIBUNG | Intern ausgeführter Befehl |
---|---|---|---|
Linux/macOS | unspecified | Die 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} |
Alle | bash | Dies 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} |
All | pwsh | Der PowerShell Core. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. | pwsh -command ". '{0}'" |
Alle | python | Führt den Befehl Python aus. | python {0} |
Linux/macOS | sh | Dies ist das Fallbackverhalten für Nicht-Windows-Plattformen, falls keine Shell bereitgestellt ist und bash nicht im Pfad gefunden wird. | sh -e {0} |
Windows | cmd | GitHub fügt die Erweiterung .cmd an deinen Skriptnamen an und ersetzt {0} . | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | Dies 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}'" . |
Windows | powershell | PowerShell Desktop. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. | powershell -command ". '{0}'" . |
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.working-directory
Nutzen von working-directory
zum Definieren des Arbeitsverzeichnisses für shell
eines Schritts. Dieses Schlüsselwort kann auf mehrere Kontexte verweisen. Weitere Informationen findest du unter Kontexte.
Tipp: Stellen Sie sicher, dass die Zuweisung von working-directory
auf dem Runner vorhanden ist, bevor du die Shell darin ausführst.
concurrency
Verwende concurrency
, um sicherzustellen, dass immer nur ein einziger Auftrag oder Workflow mit derselben Parallelitätsgruppe ausgeführt wird. Eine Parallelitätsgruppe kann eine beliebige Zeichenfolge oder ein beliebiger Ausdruck sein. Der Ausdruck kann nur die Kontexte github
, inputs
und vars
verwenden. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.
Du kannst concurrency
auch auf Auftragsebene angeben. Weitere Informationen findest du unter jobs.<job_id>.concurrency
.
Wenn ein gleichzeitiger Auftrag oder ein Workflow in die Warteschlange gestellt wird, wenn ein anderer Auftrag oder Workflow, der dieselbe Übereinstimmungsgruppe im Repository verwendet, in Bearbeitung ist, wird pending
der Warteschlangeauftrag oder der Workflow ausgeführt. Alle ausstehenden Aufträge oder Workflows in der Parallelitätsgruppe werden abgebrochen. Das bedeutet, dass es in einer Parallelitätsgruppe zu jedem Zeitpunkt höchstens einen ausgeführten und einen ausstehenden Auftrag geben kann.
Du kannst auch mit cancel-in-progress: true
alle derzeit ausgeführten Aufträge oder Workflows in derselben Parallelitätsgruppe abbrechen. Um aktuell ausgeführte Aufträge oder Workflows in derselben Parallelitätsgruppe bedingt abzubrechen, können Sie cancel-in-progress
als Ausdruck mit einem der zulässigen Ausdruckskontexte angeben.
Hinweise:
- Beim Namen von Parallelitätsgruppen wird die Groß-/Kleinschreibung nicht berücksichtigt. Beispielsweise werden
prod
undProd
als dieselbe Parallelitätsgruppe betrachtet. - Die Sortierung ist für Aufträge oder Workflowausführungen mit Parallelitätsgruppen nicht garantiert. Aufträge oder Workflowausführungen werden in derselben Parallelitätsgruppe in einer beliebigen Reihenfolge behandelt.
Beispiel: Verwenden der Parallelität und des Standardverhaltens
Das Standardverhalten von GitHub Actions erlaubt die gleichzeitige Ausführung mehrerer Aufträge bzw. Workflow-Läufe. Mit dem Schlüsselwort concurrency
können Sie die Nebenläufigkeit von Workflow-Läufen steuern.
Sie können das Schlüsselwort concurrency
zum Beispiel unmittelbar nach der Definition von Auslösebedingungen verwenden, um die Nebenläufigkeit ganzer Workflow-Läufe für eine bestimmte Verzweigung zu begrenzen:
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
Sie können auch die Parallelität von Aufträgen innerhalb eines Workflows begrenzen, indem Sie das Schlüsselwort concurrency
auf Auftragsebene verwenden:
on:
push:
branches:
- main
jobs:
job-1:
runs-on: ubuntu-latest
concurrency:
group: example-group
cancel-in-progress: true
Beispiel: Parallelitätsgruppen
Parallelitätsgruppen bieten eine Möglichkeit zum Verwalten und Einschränken der Ausführung von Workflowausführungen oder Aufträgen, die denselben Parallelitätsschlüssel aufweisen.
Der concurrency
-Schlüssel wird verwendet, um Workflows oder Aufträge in einer Parallelitätsgruppe zu gruppieren. Wenn Sie einen concurrency
-Schlüssel definieren, stellt GitHub Actions sicher, dass immer nur ein Workflow oder Auftrag mit diesem Schlüssel ausgeführt wird. Wenn ein neuer Workflow oder Job mit demselben concurrency
-Schlüssel gestartet wird, bricht GitHub Actions jeden bereits laufenden Workflow oder Job mit diesem Schlüssel ab. Der concurrency
-Schlüssel kann eine hartcodierte Zeichenfolge oder ein dynamischer Ausdruck sein, der Kontextvariablen enthält.
Es ist möglich, Parallelitätsbedingungen in Ihrem Workflow zu definieren, sodass der Workflow oder Auftrag zum Teil einer Parallelitätsgruppe wird.
Dies bedeutet, dass GitHub, wenn ein Workflow ausgeführt oder Auftrag gestartet wird, alle Workflowausführungen oder Aufträge abbricht, die bereits in derselben Parallelitätsgruppe ausgeführt werden. Dies ist in Szenarien hilfreich, in denen Sie parallele Ausführungen für einen bestimmten Satz von Workflows oder Aufträgen verhindern möchten, z. B. die für Bereitstellungen in einer Stagingumgebung verwendeten, um Aktionen zu verhindern, die Konflikte verursachen oder mehr Ressourcen verbrauchen könnten, als nötig.
In diesem Beispiel ist job-1
Teil einer Parallelitätsgruppe mit dem Namen staging_environment
. Dies bedeutet, dass, wenn eine neue Ausführung job-1
ausgelöst wird, alle Läufe desselben Auftrags in der bereits ausgeführten staging_environment
-Parallelitätsgruppe abgebrochen werden.
jobs:
job-1:
runs-on: ubuntu-latest
concurrency:
group: staging_environment
cancel-in-progress: true
Alternativ bedeutet die Verwendung eines dynamischen Ausdrucks wie concurrency: ci-${{ github.ref }}
in Ihrem Workflow, dass der Workflow oder Auftrag Teil einer Parallelitätsgruppe mit dem Namen ci-
gefolgt von der Referenz der Verzweigung bzw. des Tags, der den Workflow ausgelöst hat, ist. Wenn in diesem Beispiel ein neuer Commit an die Standard-Verzweigung übertragen wird, während eine vorherige Ausführung noch ausgeführt wird, wird die vorherige Ausführung abgebrochen, und die neue gestartet:
on:
push:
branches:
- main
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
Beispiel: Verwenden von Parallelität zum Abbrechen eines In-Progress-Auftrags oder Ausführens
Um Parallelität zum Abbrechen eines laufenden Auftrags zu verwenden oder in GitHub Actions auszuführen, können Sie den concurrency
-Schlüssel mit der cancel-in-progress
-Option auf true
verwenden:
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
Beachten Sie, dass in diesem Beispiel, ohne eine bestimmte Parallelitätsgruppe zu definieren, GitHub Actions jegliche laufende Ausführung eines Auftrags oder Workflows abbricht.
Beispiel: Verwenden eines Fallbackwerts
Wenn du den Gruppennamen mit einer Eigenschaft erstellst, die nur für bestimmte Ereignisse definiert ist, kannst du einen Fallbackwert verwenden. So wird beispielsweise github.head_ref
nur für pull_request
Ereignisse definiert. Wenn dein Workflow zusätzlich pull_request
zu Ereignissen auf andere Ereignisse reagiert, musst du einen Fallback bereitstellen, um einen Syntaxfehler zu vermeiden. Die folgende Parallelitätsgruppe bricht laufende Aufträge oder Ausführungen nur bei pull_request
Ereignissen ab. Wenn github.head_ref
nicht definiert ist, greift die Parallelitätsgruppe auf die Ausführungs-ID zurück, die garantiert eindeutig und für die Ausführung definiert ist.
concurrency:
group: ${{ github.head_ref || github.run_id }}
cancel-in-progress: true
Beispiel: Nur laufende Aufträge oder Ausführungen für den aktuellen Workflow abbrechen
Wenn du mehrere Workflows im selben Repository hast, müssen die Namen der Parallelitätsgruppen für alle Workflows eindeutig sein, um zu vermeiden, dass laufende Aufträge oder Ausführungen von anderen Workflows abgebrochen werden. Andernfalls werden alle zuvor ausgeführten oder ausstehenden Aufgaben abgebrochen, unabhängig vom Workflow.
Um nur die Ausführung desselben Workflows abzubrechen, kannst du die github.workflow
Eigenschaft verwenden, um die Parallelitätsgruppe zu erstellen:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
Beispiel: Nur laufende Aufträge auf bestimmten Branches abbrechen
Wenn Sie laufende Aufträge für bestimmte Branches abbrechen möchten, aber nicht für andere, können Sie bedingte Ausdrücke mit cancel-in-progress
verwenden. Sie können z. B. auf diese Weise laufende Aufträge in Entwicklungsbranches abbrechen, aber nicht in Releasebranches.
Wenn Sie die laufenden Ausführungen desselben Workflows nur abbrechen möchten, wenn sie nicht in einem Releasebranch ausgeführt werden, können Sie cancel-in-progress
auf einen Ausdruck ähnlich dem folgenden festlegen:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ !contains(github.ref, 'release/')}}
In diesem Beispiel würden mehrere Pushvorgänge zu einem release/1.2.3
-Branch die laufenden Ausführungen nicht abbrechen. Pushvorgänge zu einem anderen Branch, z. B. main
, würde laufende Ausführungen abbrechen.
jobs
Eine Workflowausführung besteht aus einem oder mehreren jobs
, die standardmäßig parallel ausgeführt werden. Um Aufträge nacheinander auszuführen, kannst du mit dem Schlüsselwort jobs.<job_id>.needs
Abhängigkeiten von anderen Aufträgen definieren.
Jeder Auftrag wird in einer durch runs-on
festgelegten Runnerumgebung ausgeführt.
Innerhalb der Nutzungsbeschränkungen des Workflows kannst Du unbegrenzt viele Jobs ausführen. Weitere Informationen zu auf GitHub gehosteten Runnern findest du unter Nutzungseinschränkungen, Abrechnung und Verwaltung und zu Nutzungseinschränkungen für selbstgehostete Runner unter Informationen zu selbstgehosteten Runnern.
Wenn du den eindeutigen Bezeichner eines Auftrags in einer Workflowausführung ermitteln musst, kannst du die GitHub Enterprise Server-API verwenden. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub Actions.
jobs.<job_id>
Verwende jobs.<job_id>
, um deinem Auftrag einen eindeutigen Bezeichner zu geben. Der Schlüssel job_id
ist ein String und der Wert umfasst eine Zuordnung der Konfigurationsdaten für den Auftrag. Du musst <job_id>
mit einer Zeichenfolge ersetzen, die für das jobs
-Objekt eindeutig ist. <job_id>
muss mit einem Buchstaben oder _
beginnen und darf nur alphanumerische Zeichen, -
oder _
enthalten.
Beispiel: Erstellen von Aufträgen
In diesem Beispiel wurden zwei Aufträge erstellt und ihre job_id
-Werte sind my_first_job
und my_second_job
.
jobs:
my_first_job:
name: My first job
my_second_job:
name: My second job
jobs.<job_id>.name
Mit jobs.<job_id>.name
legst du einen Namen für den Auftrag fest, der auf der Benutzeroberfläche von GitHub angezeigt wird.
jobs.<job_id>.permissions
Du kannst für einen spezifischen Auftrag jobs.<job_id>.permissions
verwenden, um die Standardberechtigungen zu ändern, die demGITHUB_TOKEN
gewährt werden, und können so den Zugriff nach Bedarf hinzufügen oder entfernen, um nur den erforderlich Mindestzugriff zu gewähren. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.
Wenn du die Berechtigung in einer Auftragsdefinition angibst, kannst du bei Bedarf einen anderen Satz von Berechtigungen für die GITHUB_TOKEN
für jeden Auftrag konfigurieren. Alternativ kannst du die Berechtigungen für alle Aufträge im Workflow angeben. Informationen zum Definieren von Berechtigungen auf Workflow-Ebene findest du unter permissions
.
Für jeden der verfügbaren Bereiche, die in der folgenden Tabelle dargestellt sind, kannst du eine der Berechtigungen zuweisen: read
, write
oder none
. Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none
festgelegt.
Verfügbare Bereiche und Einzelheiten dazu, was sie einer Aktion jeweils erlauben:
Scope | Erlaubt einer Aktion die Verwendung von GITHUB_TOKEN zum |
---|---|
actions | Arbeiten mit GitHub Actions. actions: write ermöglicht einer Aktion beispielsweise das Abbrechen einer Workflowausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
checks | Arbeiten mit Überprüfungsausführungen und Überprüfungssammlungen. checks: write ermöglicht einer Aktion beispielsweise das Erstellen einer Überprüfungsausführung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
contents | Arbeiten mit den Inhalten des Repositorys. contents: read ermöglicht einer Aktion beispielsweise das Auflisten der Commits, und contents:write ermöglicht der Aktion das Erstellen eines Releases. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
deployments | Arbeiten mit Bereitstellungen. deployments: write ermöglicht einer Aktion beispielsweise das Erstellen einer neuen Bereitstellung. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
discussions | Arbeiten mit GitHub Discussions. discussions: write ermöglicht einer Aktion beispielsweise das Schließen oder Löschen einer Diskussion. Weitere Informationen findest du unter Verwenden der GraphQL-API für Diskussionen. |
issues | Arbeiten mit Issues. issues: write ermöglicht einer Aktion beispielsweise das Hinzufügen eines Kommentars zu einem Issue. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
packages | Arbeiten mit GitHub Packages. packages: write ermöglicht einer Aktion beispielsweise das Hochladen und Veröffentlichen von Paketen auf GitHub Packages. Weitere Informationen findest du unter Informationen zu Berechtigungen für GitHub-Pakete. |
pages | Arbeiten mit GitHub Pages. pages: write ermöglicht einer Aktion beispielsweise das Anfordern eines GitHub Pages-Builds. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
pull-requests | Arbeiten mit Pull Requests. pull-requests: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Bezeichnung zu einem Pull Request. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
repository-projects | Arbeiten mit GitHub-Projekten (klassisch). repository-projects: write ermöglicht einer Aktion beispielsweise das Hinzufügen einer Spalte zu einem Projekt (klassisch). Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
security-events | Arbeiten mit GitHub-Codeüberprüfungen und Dependabot-Warnungen. security-events: read ermöglicht einer Aktion beispielsweise das Auflisten der Dependabot-Warnungen für das Repository, und security-events: write ermöglicht einer Aktion, den Status einer Codeüberprüfungswarnung zu aktualisieren. Weitere Informationen findest du unter Repositoryberechtigungen für „Codeüberprüfungswarnungen“ und Repositoryberechtigungen für „Dependabot-Warnungen“ in „Für GitHub Apps erforderliche Berechtigungen“. |
statuses | Arbeiten mit Commitstatus. statuses:read ermöglicht einer Aktion beispielsweise das Auflisten der Commitstatus für einen bestimmten Verweis. Weitere Informationen findest du unter Für GitHub-Apps erforderliche Berechtigungen. |
Definieren des Zugriffs für die GITHUB_TOKEN
-Bereiche
Du kannst den Zugriff definieren, den das GITHUB_TOKEN
zulässt, indem du read
, write
oder none
als Wert der verfügbaren Bereiche innerhalb des permissions
-Schlüssels angibst.
permissions:
actions: read|write|none
checks: read|write|none
contents: read|write|none
deployments: read|write|none
issues: read|write|none
discussions: read|write|none
packages: read|write|none
pages: read|write|none
pull-requests: read|write|none
repository-projects: read|write|none
security-events: read|write|none
statuses: read|write|none
Wenn du den Zugriff für einen dieser Bereiche angibst, werden alle, die nicht angegeben sind, auf none
festgelegt.
Du kannst die folgende Syntax verwenden, um einen der read-all
- oder write-all
-Zugriffe für alle verfügbaren Reservierungsumfänge zu definieren:
permissions: read-all
permissions: write-all
Du kannst die folgende Syntax verwenden, um Berechtigungen für alle verfügbaren Bereiche zu deaktivieren:
permissions: {}
Ändern der Berechtigungen in einem geforkten Repository
Darüber hinaus kannst du den permissions
-Schlüssel verwenden, um Leseberechtigungen für geforkte Repositorys hinzuzufügen oder zu entfernen, aber in der Regel kannst du keinen Schreibzugriff gewähren. Eine Ausnahme für dieses Verhalten besteht dann, wenn ein Administratorbenutzer die Option Schreibtoken an Workflows aus Pull Requests senden in den GitHub Actions-Einstellungen ausgewählt hat. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.
Beispiel: Festlegen der GITHUB_TOKEN
-Berechtigungen für einen Auftrag in einem Workflow
In diesem Beispiel werden Berechtigungen angezeigt, die für den GITHUB_TOKEN
eingestellt werden, der nur für den Auftrag namens stale
angewendet werden. Der Schreibzugriff wird für die issues
- und pull-requests
-Bereiche gewährt. Alle anderen Bereiche haben keinen Zugriff.
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v5
jobs.<job_id>.needs
Verwende jobs.<job_id>.needs
, um alle Aufträge zu identifizieren, die erfolgreich abgeschlossen sein müssen, bevor dieser Auftrag ausgeführt wird. Hier ist ein String oder ein Array mit Strings zulässig. Wenn ein Auftrag fehlschlägt oder übersprungen wird, werden alle Aufträge übersprungen, die diesen Auftrag benötigen, außer die Aufträge umfassen einen bedingte Ausdruck, mit dem der Auftrag dennoch fortgesetzt wird. Wenn eine Ausführung eine Reihe von Aufträgen enthält, die voneinander abhängig sind, wird ein Fehler oder eine Auslassung auf alle Aufträge in der Abhängigkeitskette ab dem Fehler- oder Auslassungspunkt angewendet. Wenn ein Auftrag auch dann ausgeführt werden soll, wenn ein Auftrag, von dem er abhängig ist, nicht erfolgreich war, verwenden Sie den bedingten always()
-Ausdruck in jobs.<job_id>.if
.
Beispiel: Erfordern erfolgreicher abhängiger Aufträge
jobs:
job1:
job2:
needs: job1
job3:
needs: [job1, job2]
In diesem Beispiel muss job1
erfolgreich abgeschlossen sein, bevor job2
beginnt, und job3
wartet darauf, dass job1
und job2
angeschlossen werden.
Die Aufträge in diesem Beispiel werden sequenziell ausgeführt:
job1
job2
job3
Beispiel: Nicht Erfordern erfolgreicher abhängiger Aufträge
jobs:
job1:
job2:
needs: job1
job3:
if: ${{ always() }}
needs: [job1, job2]
In diesem Beispiel verwendet job3
den bedingten Ausdruck always()
, sodass er immer nach Abschluss von job1
und job2
ausgeführt wird, unabhängig davon, ob sie erfolgreich waren. Weitere Informationen findest du unter Ausdrücke.
jobs.<job_id>.if
Mit der Bedingung jobs.<job_id>.if
kannst du dafür sorgen, dass ein Schritt nur ausgeführt wird, wenn eine Bedingung erfüllt ist. Du kannst eine Bedingung mit jedem unterstützten Kontext und Ausdruck erstellen. Weitere Informationen dazu, welche Kontexte in diesem Schlüssel unterstützt werden, findest du unter Kontexte.
Hinweis: Die jobs.<job_id>.if
Bedingung wird ausgewertet, bevor jobs.<job_id>.strategy.matrix
sie angewendet wird.
Wenn du Ausdrücke in einer if
-Bedingung verwendest, kannst du optional die ${{ }}
-Ausdruckssyntax weglassen, da GitHub Actions die if
-Bedingung automatisch als Ausdruck wertet. Diese Ausnahme gilt jedoch nicht überall.
Du musst immer die Syntax des ${{ }}
-Ausdrucks verwenden oder mit ''
, ""
oder ()
abbrechen, wenn der Ausdruck mit !
beginnt, da !
die reservierte Schreibweise im YAML-Format ist. Beispiel:
if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
Weitere Informationen findest du unter Ausdrücke.
Beispiel: Ausführen eines Auftrags nur für bestimmte Repositorys
In diesem Beispiel wird if
verwendet, um zu steuern, wann der Auftrag production-deploy
ausgeführt werden kann. Er wird nur ausgeführt, wenn das Repository octo-repo-prod
heißt und sich innerhalb der Organisation octo-org
befindet. Andernfalls wird der Auftrag als übersprungen markiert.
name: example-workflow on: [push] jobs: production-deploy: if: github.repository == 'octo-org/octo-repo-prod' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '14' - run: npm install -g bats
name: example-workflow
on: [push]
jobs:
production-deploy:
if: github.repository == 'octo-org/octo-repo-prod'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
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 oder ihrer Gruppenmitgliedschaft oder einer Kombination aus diesen als Ziel festlegen.
-
Du kannst
runs-on
als Folgendes angeben:- als einzelne Zeichenfolge
- als einzelne Variable, die eine Zeichenfolge enthält
- als ein Array von Zeichenfolgen, als Variablen, die Zeichenfolgen enthalten, oder als eine Kombination aus diesen beiden Optionen
- ein
key: value
Paar, das die Tastengroup
verwendetlabels
-
Wenn du ein Array von Zeichenfolgen oder Variablen angibst, wird dein Workflow auf jedem Runner ausgeführt, der allen angegebenen
runs-on
-Werten entspricht. Hier wird der Auftrag beispielsweise nur auf einem selbstgehosteten Runner mit den Bezeichnungenlinux
,x64
undgpu
ausgeführt:runs-on: [self-hosted, linux, x64, gpu]
Weitere Informationen findest du unter Auswählen von selbstgehosteten Runnern.
-
Du kannst Zeichenfolgen und Variablen in einem Array mischen. Beispiel:
on: workflow_dispatch: inputs: chosen-os: required: true type: choice options: - Ubuntu - macOS jobs: test: runs-on: [self-hosted, "${{ inputs.chosen-os }}"] steps: - run: echo Hello world!
-
Wenn du deinen Workflow auf mehreren Computern ausführen möchtest, verwende
jobs.<job_id>.strategy
.
Hinweis: Anführungszeichen sind für einfache Zeichenfolgen wie z. B. self-hosted
nicht erforderlich, aber sie sind für Ausdrücke wie "${{ inputs.chosen-os }}"
erforderlich.
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 Bezeichnungen von GitHub-gehostete Runnern sind:
OS (YAML-Workflow-Kennzeichnung) | Hinweise |
---|---|
ubuntu-latest , ubuntu-22.04 , ubuntu-20.04
|
Die ubuntu-latest -Bezeichnung verwendet derzeit das Ubuntu 22.04-Runner-Image.
|
windows-latest , windows-2022 , windows-2019
|
Die windows-latest -Bezeichnung verwendet derzeit das Windows 2022-Runner-Image.
|
macos-latest , macos-14 [Beta], macos-13 , macos-12 , macos-11
|
Die macos-latest -Workflowbezeichnung verwendet derzeit das macOS 12-Runnerimage.
|
Weitere Informationen zu Spezifikationen von auf GitHub gehosteten Runnern findest du unter Informationen zu von GitHub gehostete Runnern.
Hinweis: Die -latest
-Runner-Images sind die neuesten stabilen Images, die GitHub bereitstellt, und entsprechen möglicherweise nicht der neuesten Version des Betriebssystems, die beim Betriebssystemanbieter erhältlich ist.
Warnung: Beta- und veraltete Images werden „wie gesehen“, „mit allen Mängeln“ und „wie verfügbar“ bereitgestellt und sind von der Vereinbarung zum Servicelevel und der Garantie ausgeschlossen. Beta-Images werden möglicherweise nicht vom Kundendienst abgedeckt.
Beispiel: Angeben eines Betriebssystems
runs-on: ubuntu-latest
Weitere Informationen findest du unter Verwenden von auf GitHub gehosteten Runnern.
Auswählen von selbstgehosteten Runnern
Um einen selbstgehosteten Runner für deinen Auftrag anzugeben, konfiguriere runs-on
in deiner Workflowdatei mit Bezeichnungen selbstgehosteter Runner.
Alle selbstgehosteten Runner weisen die Bezeichnung self-hosted
auf. Wenn du nur diese Bezeichnung verwendest, werden dadurch alle selbstgehosteten Runner ausgewählt. Um Runner auszuwählen, die bestimmte Kriterien erfüllen, z. B. im Hinblick auf Betriebssystem oder Architektur, empfehlen wir die Angabe eines Arrays von Bezeichnungen, das mit self-hosted
beginnt (diese Bezeichnung muss als Erstes aufgeführt werden) und dann nach Bedarf weitere Bezeichnungen einschließt. Wenn du ein Array von Bezeichnungen angibst, werden Aufträge in die Warteschlange von Runnern eingereiht, die alle von dir angegebenen Bezeichnungen aufweisen.
Die Bezeichnung self-hosted
ist zwar nicht erforderlich, wird aber bei Verwendung selbstgehosteter Runner dringend empfohlen. So wird sichergestellt, dass in deinem Auftrag nicht versehentlich aktuelle oder zukünftige von GitHub gehostete Runner angegeben werden.
Beispiel: Verwenden von Bezeichnungen für die Auswahl von Runnern
runs-on: [self-hosted, linux]
Weitere Informationen findest du unter Informationen zu selbstgehosteten Runnern und unter Verwenden von selbstgehosteten Runnern in einem Workflow.
Auswählen von Runnern in einer Gruppe
Du kannst runs-on
verwenden, um Runnergruppen als Ziel zu verwenden, sodass der Auftrag auf jedem Runner ausgeführt wird, der Mitglied dieser Gruppe ist. Für eine präzisere Steuerung kannst du auch Runnergruppen mit Bezeichnungen kombinieren.
Beispiel: Verwenden von Gruppen zum Steuern, wo Aufträge ausgeführt werden
In diesem Beispiel wurden Ubuntu-Runner zu einer Gruppe namens ubuntu-runners
hinzugefügt. Der runs-on
-Schlüssel sendet den Auftrag an einen beliebigen verfügbaren Runner in der Gruppe ubuntu-runners
:
name: learn-github-actions
on: [push]
jobs:
check-bats-version:
runs-on:
group: ubuntu-runners
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
Beispiel: Kombinieren von Gruppen und Bezeichnungen
Wenn du Gruppen und Bezeichnungen kombinierst, muss der Runner beide Anforderungen erfüllen, um zum Ausführen des Auftrags berechtigt zu sein.
In diesem Beispiel wird eine Runnergruppe namens ubuntu-runners
mit Ubuntu-Runnern aufgefüllt, denen zudem die Bezeichnung ubuntu-20.04-16core
zugewiesen wurde. Der runs-on
-Schlüssel kombiniert group
und labels
, sodass der Auftrag an einen beliebigen verfügbaren Runner innerhalb der Gruppe weitergeleitet wird, der auch eine übereinstimmende Bezeichnung aufweist:
name: learn-github-actions
on: [push]
jobs:
check-bats-version:
runs-on:
group: ubuntu-runners
labels: ubuntu-20.04-16core
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
Beispiel: Verwenden von Präfixen zum Unterscheiden von Runnergruppen
Wenn du beispielsweise eine Runnergruppe mit dem Namen my-group
in der Organisation und eine andere Gruppe mit dem Namen my-group
im Unternehmen hast, kannst du deine Workflowdatei aktualisieren, sodass org/my-group
oder ent/my-group
verwendet wird, um zwischen den beiden Gruppen zu unterscheiden.
Verwenden von org/
:
runs-on:
group: org/my-group
labels: [ self-hosted, label-1 ]
Verwenden von ent/
:
runs-on:
group: ent/my-group
labels: [ self-hosted, label-1 ]
jobs.<job_id>.environment
Verwende jobs.<job_id>.environment
zum Definieren der Umgebung, auf die der Auftrag verweist. Alle Umgebungsschutzregeln müssen erfüllt sein, bevor ein Auftrag, der auf die Umgebung verweist, an einen Runner gesendet wird. Weitere Informationen findest du unter Verwenden von Umgebungen für die Bereitstellung.
Du kannst die Umgebung nur mit dem name
-Wert oder als Umgebungsobjekt mit name
und url
bereitstellen. Die URL entspricht environment_url
ist in der Bereitstellungs-API. Weitere Informationen zu den Bereitstellungs-API findest du unter REST-API-Endpunkte für Repositorys.
Beispiel: Verwenden eines einzelnen Umgebungsnamens
environment: staging_environment
Beispiel: Verwenden von Umgebungsnamen und URL
environment:
name: production_environment
url: https://github.com
Der Wert von url
kann ein Ausdruck sein. Zulässiger Ausdruckskontext: github
, inputs
, vars
, needs
, strategy
, matrix
, job
, runner
und env
. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.
Beispiel: Verwenden der Ausgabe als URL
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
Der Wert von name
kann ein Ausdruck sein. Zulässiger Ausdruckskontext: github
, inputs
, vars
, needs
, strategy
und matrix
. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.
Beispiel: Verwenden eines Ausdrucks als Umgebungsname
environment:
name: ${{ github.ref_name }}
jobs.<job_id>.concurrency
Du kannst jobs.<job_id>.concurrency
verwenden, um sicherzustellen, dass immer nur ein einzelner Auftrag oder Workflow mit der gleichen Parallelitätsgruppe ausgeführt wird. Eine Parallelitätsgruppe kann eine beliebige Zeichenfolge oder ein beliebiger Ausdruck sein. Zulässiger Ausdruckskontext: github
, inputs
, vars
, needs
, strategy
und matrix
. Weitere Informationen zu Ausdrücken findest du unter Ausdrücke.
concurrency
kann auch auf Workflowebene angegeben werden. Weitere Informationen findest du unter concurrency
.
Wenn ein gleichzeitiger Auftrag oder ein Workflow in die Warteschlange gestellt wird, wenn ein anderer Auftrag oder Workflow, der dieselbe Übereinstimmungsgruppe im Repository verwendet, in Bearbeitung ist, wird pending
der Warteschlangeauftrag oder der Workflow ausgeführt. Alle ausstehenden Aufträge oder Workflows in der Parallelitätsgruppe werden abgebrochen. Das bedeutet, dass es in einer Parallelitätsgruppe zu jedem Zeitpunkt höchstens einen ausgeführten und einen ausstehenden Auftrag geben kann.
Du kannst auch mit cancel-in-progress: true
alle derzeit ausgeführten Aufträge oder Workflows in derselben Parallelitätsgruppe abbrechen. Um aktuell ausgeführte Aufträge oder Workflows in derselben Parallelitätsgruppe bedingt abzubrechen, können Sie cancel-in-progress
als Ausdruck mit einem der zulässigen Ausdruckskontexte angeben.
Hinweise:
- Beim Namen von Parallelitätsgruppen wird die Groß-/Kleinschreibung nicht berücksichtigt. Beispielsweise werden
prod
undProd
als dieselbe Parallelitätsgruppe betrachtet. - Die Sortierung ist für Aufträge oder Workflowausführungen mit Parallelitätsgruppen nicht garantiert. Aufträge oder Workflowausführungen werden in derselben Parallelitätsgruppe in einer beliebigen Reihenfolge behandelt.
Beispiel: Verwenden der Parallelität und des Standardverhaltens
Das Standardverhalten von GitHub Actions erlaubt die gleichzeitige Ausführung mehrerer Aufträge bzw. Workflow-Läufe. Mit dem Schlüsselwort concurrency
können Sie die Nebenläufigkeit von Workflow-Läufen steuern.
Sie können das Schlüsselwort concurrency
zum Beispiel unmittelbar nach der Definition von Auslösebedingungen verwenden, um die Nebenläufigkeit ganzer Workflow-Läufe für eine bestimmte Verzweigung zu begrenzen:
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
Sie können auch die Parallelität von Aufträgen innerhalb eines Workflows begrenzen, indem Sie das Schlüsselwort concurrency
auf Auftragsebene verwenden:
on:
push:
branches:
- main
jobs:
job-1:
runs-on: ubuntu-latest
concurrency:
group: example-group
cancel-in-progress: true
Beispiel: Parallelitätsgruppen
Parallelitätsgruppen bieten eine Möglichkeit zum Verwalten und Einschränken der Ausführung von Workflowausführungen oder Aufträgen, die denselben Parallelitätsschlüssel aufweisen.
Der concurrency
-Schlüssel wird verwendet, um Workflows oder Aufträge in einer Parallelitätsgruppe zu gruppieren. Wenn Sie einen concurrency
-Schlüssel definieren, stellt GitHub Actions sicher, dass immer nur ein Workflow oder Auftrag mit diesem Schlüssel ausgeführt wird. Wenn ein neuer Workflow oder Job mit demselben concurrency
-Schlüssel gestartet wird, bricht GitHub Actions jeden bereits laufenden Workflow oder Job mit diesem Schlüssel ab. Der concurrency
-Schlüssel kann eine hartcodierte Zeichenfolge oder ein dynamischer Ausdruck sein, der Kontextvariablen enthält.
Es ist möglich, Parallelitätsbedingungen in Ihrem Workflow zu definieren, sodass der Workflow oder Auftrag zum Teil einer Parallelitätsgruppe wird.
Dies bedeutet, dass GitHub, wenn ein Workflow ausgeführt oder Auftrag gestartet wird, alle Workflowausführungen oder Aufträge abbricht, die bereits in derselben Parallelitätsgruppe ausgeführt werden. Dies ist in Szenarien hilfreich, in denen Sie parallele Ausführungen für einen bestimmten Satz von Workflows oder Aufträgen verhindern möchten, z. B. die für Bereitstellungen in einer Stagingumgebung verwendeten, um Aktionen zu verhindern, die Konflikte verursachen oder mehr Ressourcen verbrauchen könnten, als nötig.
In diesem Beispiel ist job-1
Teil einer Parallelitätsgruppe mit dem Namen staging_environment
. Dies bedeutet, dass, wenn eine neue Ausführung job-1
ausgelöst wird, alle Läufe desselben Auftrags in der bereits ausgeführten staging_environment
-Parallelitätsgruppe abgebrochen werden.
jobs:
job-1:
runs-on: ubuntu-latest
concurrency:
group: staging_environment
cancel-in-progress: true
Alternativ bedeutet die Verwendung eines dynamischen Ausdrucks wie concurrency: ci-${{ github.ref }}
in Ihrem Workflow, dass der Workflow oder Auftrag Teil einer Parallelitätsgruppe mit dem Namen ci-
gefolgt von der Referenz der Verzweigung bzw. des Tags, der den Workflow ausgelöst hat, ist. Wenn in diesem Beispiel ein neuer Commit an die Standard-Verzweigung übertragen wird, während eine vorherige Ausführung noch ausgeführt wird, wird die vorherige Ausführung abgebrochen, und die neue gestartet:
on:
push:
branches:
- main
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
Beispiel: Verwenden von Parallelität zum Abbrechen eines In-Progress-Auftrags oder Ausführens
Um Parallelität zum Abbrechen eines laufenden Auftrags zu verwenden oder in GitHub Actions auszuführen, können Sie den concurrency
-Schlüssel mit der cancel-in-progress
-Option auf true
verwenden:
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
Beachten Sie, dass in diesem Beispiel, ohne eine bestimmte Parallelitätsgruppe zu definieren, GitHub Actions jegliche laufende Ausführung eines Auftrags oder Workflows abbricht.
Beispiel: Verwenden eines Fallbackwerts
Wenn du den Gruppennamen mit einer Eigenschaft erstellst, die nur für bestimmte Ereignisse definiert ist, kannst du einen Fallbackwert verwenden. So wird beispielsweise github.head_ref
nur für pull_request
Ereignisse definiert. Wenn dein Workflow zusätzlich pull_request
zu Ereignissen auf andere Ereignisse reagiert, musst du einen Fallback bereitstellen, um einen Syntaxfehler zu vermeiden. Die folgende Parallelitätsgruppe bricht laufende Aufträge oder Ausführungen nur bei pull_request
Ereignissen ab. Wenn github.head_ref
nicht definiert ist, greift die Parallelitätsgruppe auf die Ausführungs-ID zurück, die garantiert eindeutig und für die Ausführung definiert ist.
concurrency:
group: ${{ github.head_ref || github.run_id }}
cancel-in-progress: true
Beispiel: Nur laufende Aufträge oder Ausführungen für den aktuellen Workflow abbrechen
Wenn du mehrere Workflows im selben Repository hast, müssen die Namen der Parallelitätsgruppen für alle Workflows eindeutig sein, um zu vermeiden, dass laufende Aufträge oder Ausführungen von anderen Workflows abgebrochen werden. Andernfalls werden alle zuvor ausgeführten oder ausstehenden Aufgaben abgebrochen, unabhängig vom Workflow.
Um nur die Ausführung desselben Workflows abzubrechen, kannst du die github.workflow
Eigenschaft verwenden, um die Parallelitätsgruppe zu erstellen:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
Beispiel: Nur laufende Aufträge auf bestimmten Branches abbrechen
Wenn Sie laufende Aufträge für bestimmte Branches abbrechen möchten, aber nicht für andere, können Sie bedingte Ausdrücke mit cancel-in-progress
verwenden. Sie können z. B. auf diese Weise laufende Aufträge in Entwicklungsbranches abbrechen, aber nicht in Releasebranches.
Wenn Sie die laufenden Ausführungen desselben Workflows nur abbrechen möchten, wenn sie nicht in einem Releasebranch ausgeführt werden, können Sie cancel-in-progress
auf einen Ausdruck ähnlich dem folgenden festlegen:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ !contains(github.ref, 'release/')}}
In diesem Beispiel würden mehrere Pushvorgänge zu einem release/1.2.3
-Branch die laufenden Ausführungen nicht abbrechen. Pushvorgänge zu einem anderen Branch, z. B. main
, würde laufende Ausführungen abbrechen.
jobs.<job_id>.outputs
Du kannst jobs.<job_id>.outputs
verwenden, um eine map
von Ausgaben für einen Auftrag zu erstellen. Ausgaben eines Jobs stehen allen nachgelagerten Jobs zur Verfügung, die von diesem Job abhängen. Weitere Informationen zum Definieren von Auftragsabhängigkeiten findest du unter jobs.<job_id>.needs
.
Ausgaben sind Unicode-Zeichenfolgen und können maximal 1 MB groß sein. Die Gesamtanzahl aller Ausgaben in einer Workflowausführung kann maximal 50 MB betragen.
Ausgaben von Aufträgen, die Ausdrücke enthalten, werden am Ende jedes Auftrags auf dem Runner ausgewertet. Ausgaben, die Geheimnisse enthalten, werden auf dem Runner zensiert und nicht an GitHub Actions gesendet.
Um Auftragsausgaben in einem abhängigen Auftrag zu verwenden, kannst du den needs
-Kontext verwenden. Weitere Informationen finden Sie unter Kontexte.
Hinweis: $GITHUB_OUTPUT
wird zwischen allen Schritten in einem Job geteilt. Wenn Sie denselben Ausgabenamen in mehreren Schritten verwenden, setzt der letzte Schritt zum Schreiben in die Ausgabe den Wert außer Kraft. Wenn Ihr Job eine Matrix verwendet und in $GITHUB_OUTPUT
schreibt, wird der Inhalt für jede Matrixkombination überschrieben. Sie können den matrix
Kontext verwenden, um eindeutige Ausgabenamen für jede Job-Konfiguration zu erstellen. Weitere Informationen finden Sie unter Kontexte.
Beispiel: Definieren von Ausgaben für einen Auftrag
jobs:
job1:
runs-on: ubuntu-latest
# Map a step output to a job output
outputs:
output1: ${{ steps.step1.outputs.test }}
output2: ${{ steps.step2.outputs.test }}
steps:
- id: step1
run: echo "test=hello" >> "$GITHUB_OUTPUT"
- id: step2
run: echo "test=world" >> "$GITHUB_OUTPUT"
job2:
runs-on: ubuntu-latest
needs: job1
steps:
- env:
OUTPUT1: ${{needs.job1.outputs.output1}}
OUTPUT2: ${{needs.job1.outputs.output2}}
run: echo "$OUTPUT1 $OUTPUT2"
jobs.<job_id>.env
Dies ist eine map
von Variablen, die für alle Schritte im Auftrag verfügbar sind. Du kannst Variablen für den gesamten Workflow oder für einen einzelnen Schritt festlegen. Weitere Informationen findest du unter env
und jobs.<job_id>.steps[*].env
.
Wenn mehr als eine Umgebungsvariable mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Variable. Beispielsweise setzt eine in einem Schritt definierte Umgebungsvariable Auftrags- und Workflowumgebungsvariablen mit demselben Namen außer Kraft, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Umgebungsvariable setzt eine Workflowvariable mit demselben Namen außer Kraft, während der Auftrag ausgeführt wird.
Beispiel für jobs.<job_id>.env
jobs:
job1:
env:
FIRST_NAME: Mona
jobs.<job_id>.defaults
Verwende jobs.<job_id>.defaults
, um eine map
mit Standardeinstellungen zu erstellen, die für alle Schritte im Auftrag gelten. Du kannst auch Standardeinstellungen für den gesamten Workflow festlegen. Weitere Informationen findest du unter defaults
.
Wenn mehr als eine Standardeinstellung mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Standardeinstellung. Beispielsweise wird eine in einem Auftrag definierte Standardeinstellung die gleichnamig definierte Standardeinstellung in einem Workflow überschreiben.
jobs.<job_id>.defaults.run
Verwende jobs.<job_id>.defaults.run
, um für alle run
-Schritte im Auftrag eine Standardeinstellung für shell
und working-directory
bereitzustellen.
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 finden Sie unter defaults.run
.
Diese können auf den Ebenen jobs.<job_id>.defaults.run
und jobs.<job_id>.steps[*].run
überschrieben werden.
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.shell
Nutzen von shell
zum Definieren von shell
eines Schritts. Dieses Schlüsselwort kann auf mehrere Kontexte verweisen. Weitere Informationen findest du unter Kontexte.
Unterstützte Plattform | shell -Parameter | BESCHREIBUNG | Intern ausgeführter Befehl |
---|---|---|---|
Linux/macOS | unspecified | Die 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} |
Alle | bash | Dies 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} |
All | pwsh | Der PowerShell Core. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. | pwsh -command ". '{0}'" |
Alle | python | Führt den Befehl Python aus. | python {0} |
Linux/macOS | sh | Dies ist das Fallbackverhalten für Nicht-Windows-Plattformen, falls keine Shell bereitgestellt ist und bash nicht im Pfad gefunden wird. | sh -e {0} |
Windows | cmd | GitHub fügt die Erweiterung .cmd an deinen Skriptnamen an und ersetzt {0} . | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | Dies 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}'" . |
Windows | powershell | PowerShell Desktop. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. | powershell -command ". '{0}'" . |
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.working-directory
Nutzen von working-directory
zum Definieren des Arbeitsverzeichnisses für shell
eines Schritts. Dieses Schlüsselwort kann auf mehrere Kontexte verweisen. Weitere Informationen findest du unter Kontexte.
Tipp: Stellen Sie sicher, dass die Zuweisung von working-directory
auf dem Runner vorhanden ist, bevor du die Shell darin ausführst.
Beispiel: Festlegen von Standardoptionen für den run
-Schritt für einen Auftrag
jobs:
job1:
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: ./scripts
jobs.<job_id>.steps
Ein Auftrag enthält eine Sequenz von Aufgaben (als steps
bezeichnet). Mit Schritten können Befehle oder Einrichtungsaufgaben ausgeführt werden, und außerdem Aktionen, die sich in deinem Repository oder in einem öffentlichen Repository befinden oder in einer Docker Registry veröffentlicht sind. Nicht alle Schritte führen Aktionen aus, doch alle Aktionen werden als Schritt ausgeführt. Jeder Schritt wird in einem eigenen Prozess in der Runner-Umgebung ausgeführt. Er hat Zugriff auf den Arbeitsbereich und das Dateisystem. Da die Schritte jeweils in einem eigenen Prozess laufen, werden Änderungen an den Umgebungsvariablen nicht von einem Schritt zum nächsten beibehalten. GitHub umfasst integrierte Schritte zum Einrichten und Ausführen eines Jobs.
GitHub zeigt nur die ersten 1.000 Prüfungen an. Sie können jedoch eine unbegrenzte Anzahl von Schritten ausführen, solange Sie sich innerhalb der Grenzwerte für die Workflownutzung befinden. Weitere Informationen zu auf GitHub gehosteten Runnern findest du unter Nutzungseinschränkungen, Abrechnung und Verwaltung und zu Nutzungseinschränkungen für selbstgehostete Runner unter Informationen zu selbstgehosteten Runnern.
Beispiel für jobs.<job_id>.steps
name: Greeting from Mona
on: push
jobs:
my-job:
name: My Job
runs-on: ubuntu-latest
steps:
- name: Print a greeting
env:
MY_VAR: Hi there! My name is
FIRST_NAME: Mona
MIDDLE_NAME: The
LAST_NAME: Octocat
run: |
echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.
jobs.<job_id>.steps[*].id
Eine eindeutige Kennung für den Schritt. Du kannst mit id
auf den Schritt in Kontexten verweisen. Weitere Informationen findest du unter Kontexte.
jobs.<job_id>.steps[*].if
Du kannst die if
-Bedingung verwenden, um zu verhindern, dass ein Schritt ausgeführt wird – es sei denn, eine Bedingung ist erfüllt. Du kannst eine Bedingung mit jedem unterstützten Kontext und Ausdruck erstellen. Weitere Informationen dazu, welche Kontexte in diesem Schlüssel unterstützt werden, findest du unter Kontexte.
Wenn du Ausdrücke in einer if
-Bedingung verwendest, kannst du optional die ${{ }}
-Ausdruckssyntax weglassen, da GitHub Actions die if
-Bedingung automatisch als Ausdruck wertet. Diese Ausnahme gilt jedoch nicht überall.
Du musst immer die Syntax des ${{ }}
-Ausdrucks verwenden oder mit ''
, ""
oder ()
abbrechen, wenn der Ausdruck mit !
beginnt, da !
die reservierte Schreibweise im YAML-Format ist. Beispiel:
if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
Weitere Informationen findest du unter Ausdrücke.
Beispiel: Verwenden von Kontexten
Dieser Schritt wird nur ausgeführt, wenn der Ereignistyp pull_request
und die Ereignisaktion unassigned
lautet.
steps:
- name: My first step
if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
run: echo This event is a pull request that had an assignee removed.
Beispiel: Verwenden von Funktionen zur Statusüberprüfung
my backup step
wird nur ausgeführt, wenn beim vorherigen Schritt eines Auftrags ein Fehler auftritt. Weitere Informationen findest du unter Ausdrücke.
steps:
- name: My first step
uses: octo-org/action-name@main
- name: My backup step
if: ${{ failure() }}
uses: actions/heroku@1.0.0
Beispiel: Verwenden von Geheimnissen
Auf Geheimnisse kann nicht direkt in if:
-Bedingungen verwiesen werden. Erwäge stattdessen, Geheimnisse als Umgebungsvariablen auf Auftragsebene festzulegen, und verweise dann auf die Umgebungsvariablen, um Schritte im Auftrag bedingt auszuführen.
Wenn kein Geheimnis festgelegt wurde, ist der Rückgabewert eines Ausdrucks, der auf das Geheimnis verweist (z. B. ${{ secrets.SuperSecret }}
im Beispiel), eine leere Zeichenfolge.
name: Run a step if a secret has been set
on: push
jobs:
my-jobname:
runs-on: ubuntu-latest
env:
super_secret: ${{ secrets.SuperSecret }}
steps:
- if: ${{ env.super_secret != '' }}
run: echo 'This step will only run if the secret has a value set.'
- if: ${{ env.super_secret == '' }}
run: echo 'This step will only run if the secret does not have a value set.'
Weitere Informationen finden Sie unter Kontexte und unter Verwenden von Geheimnissen in GitHub-Aktionen.
jobs.<job_id>.steps[*].name
Name deines Schritts, der auf GitHub angezeigt wird.
jobs.<job_id>.steps[*].uses
Wählt eine Aktion aus, die als Teil eines Schritts im Job ausgeführt wird. Eine Aktion ist eine wiederverwendbare Code-Einheit. Du kannst eine Aktion verwenden, die im selben Repository wie der Workflow, in einem öffentlichen Repository oder in einem veröffentlichten Docker-Containerimage definiert ist.
Es wird dringend empfohlen, dass du die Version der verwendeten Aktion einschließt, indem du Git-ref, SHA oder ein Docker-Tag angibst. Wenn du keine Version angibst, könnten damit die Workflows gestört werden, oder es wird ein unerwartetes Verhalten hervorgerufen, wenn der bzw. die Besitzer*in der Aktion eine Aktualisierung veröffentlicht.
- Am besten in Hinblick auf Stabilität und Sicherheit ist es, die Commit-SHA einer freigegebenen Version einer Aktion zu verwenden.
- Wenn die Aktion Hauptversionstags veröffentlicht, kannst du kritische Fehlerbehebungen und Sicherheitspatches erhalten und gleichzeitig die Kompatibilität wahren. Hinweis: Dieses Verhalten liegt im Ermessen des Autors der Aktion.
- Die Verwendung des Standardbranches einer Aktion ist zwar auf den ersten Blick praktisch, doch wenn eine neue Hauptversion mit einem Breaking Change veröffentlicht wird, könnte der Workflow unterbrochen werden.
Einige Aktionen erfordern Eingaben, die du mit dem Schlüsselwort with
festlegen musst. Die erforderlichen Eingaben findest du in der README-Datei der Aktion.
Aktionen sind entweder JavaScript-Dateien oder Docker-Container. Bei Docker-Containern als Aktion musst du den Auftrag in einer Linux-Umgebung ausführen. Weitere Informationen findest du unter runs-on
.
Beispiel: Verwenden versionierter Aktionen
steps:
# Reference a specific commit
- uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
# Reference the major version of a release
- uses: actions/checkout@v4
# Reference a specific version
- uses: actions/checkout@v4.2.0
# Reference a branch
- uses: actions/checkout@main
Beispiel: Verwenden einer öffentlichen Aktion
{owner}/{repo}@{ref}
Du kannst einen Branch, einen Verweis oder einen SHA-Wert in einem öffentlichen GitHub-Repository angeben.
jobs:
my_first_job:
steps:
- name: My first step
# Uses the default branch of a public repository
uses: actions/heroku@main
- name: My second step
# Uses a specific version tag of a public repository
uses: actions/aws@v2.0.1
Beispiel: Verwenden einer öffentlichen Aktion in einem Unterverzeichnis
{owner}/{repo}/{path}@{ref}
Ein Unterverzeichnis in einem öffentlichen Repository auf GitHub in einem bestimmten Branch, einer bestimmten Ref oder einer bestimmten SHA.
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/aws/ec2@main
Beispiel: Verwenden einer Aktion im selben Repository wie der Workflow
./path/to/dir
Der Pfad zum Verzeichnis, das die Aktion im Repository deines Workflows enthält. Du musst dein Repository auschecken, bevor du die Aktion verwendest.
Example repository file structure:
|-- hello-world (repository)
| |__ .github
| └── workflows
| └── my-first-workflow.yml
| └── actions
| |__ hello-world-action
| └── action.yml
The path is relative (./
) to the default working directory (github.workspace
, $GITHUB_WORKSPACE
). If the action checks out the repository to a location different than the workflow, the relative path used for local actions must be updated.
Example workflow file:
jobs:
my_first_job:
runs-on: ubuntu-latest
steps:
# This step checks out a copy of your repository.
- name: My first step - check out repository
uses: actions/checkout@v4
# This step references the directory that contains the action.
- name: Use local hello-world-action
uses: ./.github/actions/hello-world-action
Beispiel: Verwenden einer Docker Hub-Aktion
docker://{image}:{tag}
Dies ist ein Docker-Image, das in Docker Hub veröffentlicht wurde.
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://alpine:3.8
Beispiel: Verwenden einer Aktion in einer öffentlichen Docker-Registrierung
docker://{host}/{image}:{tag}
Ein Docker-Image in einer öffentlichen Registry. Dieses Beispiel verwendet die Google Container Registry unter gcr.io
.
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://gcr.io/cloud-builders/gradle
Beispiel: Verwenden einer Aktion innerhalb eines anderen privaten Repositorys als dem Workflow
Dein Workflow muss das private Repository auschecken und lokal auf die Aktion verweisen. Generiere ein personal access token, und füge das Token als Geheimnis hinzu. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken und unter Verwenden von Geheimnissen in GitHub-Aktionen.
Ersetze PERSONAL_ACCESS_TOKEN
im Beispiel durch den Namen deines Geheimnisses.
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v4
with:
repository: octocat/my-private-repo
ref: v1.0
token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
path: ./.github/actions/my-private-repo
- name: Run my action
uses: ./.github/actions/my-private-repo/my-action
Alternativ kannst du eine GitHub App anstelle eines personal access token verwenden, um sicherzustellen, dass dein Workflow auch dann ausgeführt wird, wenn derdie personal access token-Besitzerin nicht mehr da ist. Weitere Informationen findest du unter Authentifizierte API-Anforderungen mit einer GitHub-App in einem GitHub Actions-Workflow.
jobs.<job_id>.steps[*].run
Führt Befehlszeilenprogramme aus, die nicht mehr als 21 000 Zeichen umfassen, und verwendet dabei die Shell des Betriebssystems. Wenn du keinen name
angibst, wird standardmäßig der im run
-Befehl angegebene Text als Schrittname verwendet.
Befehle greifen standardmäßig auf Shells zurück, für die keine Anmeldung erforderlich ist. Du kannst für die Ausführung von Befehlen eine andere Shell auswählen und die Shell anpassen. Weitere Informationen findest du unter jobs.<job_id>.steps[*].shell
.
Jedes run
-Schlüsselwort stellt einen neuen Prozess und eine neue Shell in der Runnerumgebung dar. Wenn du mehrzeilige Befehle angibst, werden alle Zeilen in derselben Shell ausgeführt. Beispiel:
-
Einzeiliger Befehl:
- name: Install Dependencies run: npm install
-
Mehrzeiliger Befehl:
- name: Clean install dependencies and build run: | npm ci npm run build
jobs.<job_id>.steps[*].working-directory
Mithilfe des working-directory
-Schlüsselworts kannst du das Arbeitsverzeichnis angeben, in dem der Befehl ausgeführt werden soll.
- name: Clean temp directory
run: rm -rf *
working-directory: ./temp
Alternativ können Sie ein Standard-Arbeitsverzeichnis für alle run
Schritte in einem Auftrag oder für alle run
Schritte im gesamten Workflow angeben. Weitere Informationen finden Sie unter „defaults.run.working-directory
“ und „jobs.<job_id>.defaults.run.working-directory
“.
Sie können auch einen run
-Schritt zum Ausführen eines Skripts verwenden. Weitere Informationen findest du unter Grundlegende Features von GitHub Actions.
jobs.<job_id>.steps[*].shell
Sie können die Standardshelleinstellungen im Betriebssystem des Runners und den Jobstandard 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 Plattform | shell -Parameter | BESCHREIBUNG | Intern ausgeführter Befehl |
---|---|---|---|
Linux/macOS | unspecified | Die 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} |
Alle | bash | Dies 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} |
All | pwsh | Der PowerShell Core. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. | pwsh -command ". '{0}'" |
Alle | python | Führt den Befehl Python aus. | python {0} |
Linux/macOS | sh | Dies ist das Fallbackverhalten für Nicht-Windows-Plattformen, falls keine Shell bereitgestellt ist und bash nicht im Pfad gefunden wird. | sh -e {0} |
Windows | cmd | GitHub fügt die Erweiterung .cmd an deinen Skriptnamen an und ersetzt {0} . | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | Dies 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}'" . |
Windows | powershell | PowerShell Desktop. GitHub fügt die Erweiterung .ps1 an deinen Skriptnamen an. | powershell -command ". '{0}'" . |
Alternativ können Sie eine Standard-Shell für alle run
Schritte in einem Auftrag oder für alle run
Schritte im gesamten Workflow angeben. Weitere Informationen finden Sie unter „defaults.run.shell
“ und „jobs.<job_id>.defaults.run.shell
“.
Beispiel: Ausführen eines Befehls mit Bash
steps:
- name: Display the path
shell: bash
run: echo $PATH
Beispiel: Ausführen eines Befehls unter Windows cmd
steps:
- name: Display the path
shell: cmd
run: echo %PATH%
Beispiel: Ausführen eines Befehls mit PowerShell Core
steps:
- name: Display the path
shell: pwsh
run: echo ${env:PATH}
Beispiel: Verwenden von PowerShell Desktop zum Ausführen eines Befehls
steps:
- name: Display the path
shell: powershell
run: echo ${env:PATH}
Beispiel: Ausführen eines Inline-Python-Skripts
steps:
- name: Display the path
shell: python
run: |
import os
print(os.environ['PATH'])
Benutzerdefinierte Shell
Du kannst den shell
-Wert mithilfe von command [options] {0} [more_options]
auf eine Vorlagenzeichenfolge festlegen. GitHub interpretiert das erste durch ein Leerzeichen getrennte Wort in der Zeichenfolge als den Befehl und fügt den Dateinamen für das temporäre Skript bei {0}
ein.
Beispiel:
steps:
- name: Display the environment variables and their values
shell: perl {0}
run: |
print %ENV
Der in diesem Beispiel verwendete Befehl perl
muss im Runner installiert werden.
Exit-Codes und Voreinstellung für Fehleraktionen
Für integrierte Shell-Schlüsselwörter gelten die folgenden Standards, die durch auf GitHub gehostete Runner ausgeführt werden. Beachte diese Richtlinien beim Ausführen von Shell-Skripts.
-
bash
/sh
:- Standardmäßig wird das Fail-Fast-Verhalten mit
set -e
sowohl fürsh
als auchbash
durchgesetzt. Wennshell: bash
angegeben ist, wird-o pipefail
ebenfalls angewendet, um die vorzeitige Beendigungen von Pipelines zu erzwingen, die einen anderen Beendigungsstatus als null generieren. - Du kannst die volle Kontrolle über Shellparameter übernehmen, indem du einen Vorlagenstring für die Shelloptionen bereitstellst. Beispiel:
bash {0}
. sh
-ähnliche Shells werden mit dem Exitcode des letzten Befehls beendet, der im Skript ausgeführt wurde. Dies ist auch das Standardverhalten für Aktionen. Der Runner meldet den Status des Schritts gemäß diesem Exitcodeode als Fehler/Erfolg.
- Standardmäßig wird das Fail-Fast-Verhalten mit
-
powershell
/pwsh
- Fail-Fast-Verhalten, soweit möglich. Bei den integrierten Shells
pwsh
undpowershell
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}
oderpowershell -Command "& '{0}'"
(je nach Bedarf) bereitzustellen.
- Fail-Fast-Verhalten, soweit möglich. Bei den integrierten Shells
-
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 vorherigensh
- undpwsh
-Standardverhalten konsistent und entspricht demcmd.exe
-Standard, sodass dieses Verhalten intakt bleibt.
jobs.<job_id>.steps[*].with
Dies ist eine map
der Eingabeparameter, die durch die Aktion definiert werden. Jeder Eingabeparameter ist ein Schlüssel-Wert-Paar. Eingabeparameter werden als Umgebungsvariablen festgelegt. Die Variable wird mit dem Präfix INPUT_
versehen und in Großbuchstaben konvertiert.
Eingabeparameter, die für einen Docker-Container definiert sind, müssen args
verwenden. Weitere Informationen findest du unter jobs.<job_id>.steps[*].with.args
.
Beispiel für jobs.<job_id>.steps[*].with
Die drei Eingabeparameter (first_name
, middle_name
und last_name
) werden durch die hello_world
-Aktion definiert. Diese Eingabevariablen sind für die hello-world
-Aktion über die Umgebungsvariablen INPUT_FIRST_NAME
, INPUT_MIDDLE_NAME
und INPUT_LAST_NAME
zugänglich.
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/hello_world@main
with:
first_name: Mona
middle_name: The
last_name: Octocat
jobs.<job_id>.steps[*].with.args
Dies ist ein string
, der die Eingaben für einen Docker-Container definiert. GitHub übergibt args
beim Start des Containers an dessen ENTRYPOINT
. Ein array of strings
wird von diesem Parameter nicht unterstützt. Ein einzelnes Argument, das Leerzeichen enthält, sollte in doppelte Anführungszeichen ""
eingeschlossen werden.
Beispiel für jobs.<job_id>.steps[*].with.args
steps:
- name: Explain why this job ran
uses: octo-org/action-name@main
with:
entrypoint: /bin/echo
args: The ${{ github.event_name }} event triggered this step.
Die args
-Elemente werden anstelle der CMD
-Anweisung in Dockerfile
verwendet. Wenn du CMD
in Dockerfile
verwendest, befolge diese Hinweise (nach Präferenz sortiert):
- Dokumentiere die erforderlichen Argumente in der README-Datei der Aktion, und lasse sie in der
CMD
-Anweisung weg. - Verwende Standardwerte, die die Verwendung der Aktion ohne die Angabe von
args
ermöglichen. - Wenn die Aktion ein
--help
-Flag oder etwas ähnliches verfügbar macht, verwende dies als Standard, damit die Aktion selbstdokumentierend wird.
jobs.<job_id>.steps[*].with.entrypoint
Hiermit wird ENTRYPOINT
für Docker in Dockerfile
überschrieben oder ein Einstiegspunkt festgelegt, falls noch keiner vorhanden ist. Im Gegensatz zur Docker-Anweisung ENTRYPOINT
mit einer Shell und einem Ausführungsformat, akzeptiert das Schlüsselwort entrypoint
nur eine einzelne Zeichenfolge, die die ausführbare Datei definiert, die ausgeführt werden soll.
Beispiel für jobs.<job_id>.steps[*].with.entrypoint
steps:
- name: Run a custom command
uses: octo-org/action-name@main
with:
entrypoint: /a/different/executable
Das Schlüsselwort entrypoint
ist für die Verwendung mit Docker-Containeraktionen vorgesehen, du kannst es jedoch auch mit JavaScript-Aktionen verwenden, die keine Eingaben definieren.
jobs.<job_id>.steps[*].env
Damit werden Variablen für Schritte festgelegt, die in der Runner-Umgebung verwendet werden sollen. Darüber hinaus kannst du Variablen für den gesamten Workflow oder für einen Auftrag festlegen. Weitere Informationen findest du unter env
und jobs.<job_id>.env
.
Wenn mehr als eine Umgebungsvariable mit dem gleichen Namen definiert ist, verwendet GitHub die spezifischste Variable. Beispielsweise setzt eine in einem Schritt definierte Umgebungsvariable Auftrags- und Workflowumgebungsvariablen mit demselben Namen außer Kraft, während der Schritt ausgeführt wird. Eine für einen Auftrag definierte Umgebungsvariable setzt eine Workflowvariable mit demselben Namen außer Kraft, während der Auftrag ausgeführt wird.
Die erwarteten Variablen können durch öffentliche Aktionen in der Infodatei angegeben werden. Wenn du einen geheimen oder vertraulichen Wert festlegst, z. B. ein Kennwort oder ein Token, musst du Geheimnisse mithilfe des Kontexts secrets
festlegen. Weitere Informationen findest du unter Kontexte.
Beispiel für jobs.<job_id>.steps[*].env
steps:
- name: My first action
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FIRST_NAME: Mona
LAST_NAME: Octocat
jobs.<job_id>.steps[*].continue-on-error
Verhindert das Fehlschlagen eines Auftrags, wenn ein Schritt fehlschlägt. Lege dies auf true
fest, damit ein Auftrag erfolgreich abgeschlossen werden kann, wenn bei diesem Schritt ein Fehler auftritt.
jobs.<job_id>.steps[*].timeout-minutes
Maximaler Zeitraum in Minuten für die Ausführung des Schritts, bevor der Prozess abgebrochen wird.
jobs.<job_id>.timeout-minutes
Die maximale Anzahl von Minuten, die ein Job ausgeführt wird, bevor GitHub automatisch abbricht. Standard: 360
Sollte das Timeout das Zeitlimit für die Auftragsausführung für den Runner überschreitet, wird der Auftrag abgebrochen, wenn stattdessen das Zeitlimit für die Ausführung erreicht wird. Weitere Informationen zu Zeitlimits von Jobausführungen auf GitHub gehosteten Runnern findest du unter Nutzungseinschränkungen, Abrechnung und Verwaltung und zu Nutzungseinschränkungen für selbstgehostete Runner unter Informationen zu selbstgehosteten Runnern.
Hinweis: GITHUB_TOKEN
läuft ab, wenn ein Auftrag beendet wird bzw. spätestens nach 24 Stunden. Für selbstgehostete Runner kann das Token der begrenzende Faktor sein, wenn das Auftragstimeout mehr als 24 Stunden beträgt. Weitere Informationen zu GITHUB_TOKEN
findest du unter Automatische Tokenauthentifizierung.
jobs.<job_id>.strategy
Mithilfe von jobs.<job_id>.strategy
kannst du eine Matrixstrategie für deine Aufträge verwenden. Mithilfe einer Matrixstrategie kannst du Variablen in einer Auftragsdefinition verwenden, um automatisch mehrere Auftragsausführungen zu erstellen, die auf Kombinationen dieser Variablen basieren. Mithilfe einer Matrixstrategie kannst du deinen Code beispielsweise in mehreren Versionen einer Sprache oder auf mehreren Betriebssystemen testen. Weitere Informationen findest du unter Verwenden von Matrizen für deine Aufträge.
jobs.<job_id>.strategy.matrix
Verwende jobs.<job_id>.strategy.matrix
, um eine Matrix verschiedener Auftragskonfigurationen zu definieren. Definiere innerhalb der Matrix eine oder mehrere Variablen, gefolgt von einem Array an Werten. Die folgende Matrix verfügt beispielsweise über eine Variable namens version
mit dem Wert [10, 12, 14]
und über eine Variable namens os
mit dem Wert [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
Für jede mögliche Kombination der Variablen wird ein Auftrag ausgeführt. In diesem Beispiel führt der Workflow sechs Aufträge aus: einen für jede Kombination der Variablen os
und version
.
Standardmäßig maximiert GitHub Enterprise 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@v4
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@v4
with:
node-version: ${{ matrix.version }}
Eine Variablenkonfiguration in einer Matrix kann ein array
von object
en sein.
matrix:
os:
- ubuntu-latest
- macos-latest
node:
- version: 14
- version: 16
env: NODE_OPTIONS=--openssl-legacy-provider
Diese Matrix erzeugt 4 Aufträge mit entsprechenden Kontexten.
- matrix.os: ubuntu-latest
matrix.node.version: 14
- matrix.os: ubuntu-latest
matrix.node.version: 16
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
matrix.node.version: 14
- matrix.os: macos-latest
matrix.node.version: 16
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
Beispiel: Erstellen von Matrizen mithilfe von Kontexten
Du kannst Kontexte verwenden, um Matrizen zu erstellen. Weitere Informationen zu Kontexten findest du unter Kontexte.
Beispielsweise wird der folgende Workflow für das repository_dispatch
-Ereignis ausgelöst und verwendet Informationen aus der Ereignisnutzlast, um die Matrix zu erstellen. Wenn ein Repositorydispatchereignis mit einer Nutzlast wie der folgenden erstellt wird, hat die Matrixvariable version
einen Wert von [12, 14, 16]
. Weitere Informationen zum Trigger repository_dispatch
findest du unter Ereignisse zum Auslösen von Workflows.
{
"event_type": "test",
"client_payload": {
"versions": [12, 14, 16]
}
}
on:
repository_dispatch:
types:
- test
jobs:
example_matrix:
runs-on: ubuntu-latest
strategy:
matrix:
version: ${{ github.event.client_payload.versions }}
steps:
- uses: actions/setup-node@v4
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ügtcolor:pink
nur den ursprünglichen Matrixkombinationen hinzu, dieanimal: cat
enthalten. Dadurch wird diecolor: green
überschrieben, die zuvor durch den vorherigeninclude
-Eintrag hinzugefügt wurde.{fruit: apple, shape: circle}
fügtshape: circle
nur den ursprünglichen Matrixkombinationen hinzu, diefruit: apple
enthalten.{fruit: banana}
kann zu keiner ursprünglichen Matrixkombination hinzugefügt werden, ohne dass dabei ein Wert überschrieben wird. Daher wird sie als zusätzliche Matrixkombination hinzugefügt.{fruit: banana, animal: cat}
kann zu keiner ursprünglichen Matrixkombination hinzugefügt werden, ohne dass dabei ein Wert überschrieben wird. Daher wird sie als zusätzliche Matrixkombination hinzugefügt. Die{fruit: banana}
-Matrixkombination wird nicht hinzugefügt, da die Kombination keine der ursprünglichen Matrixkombinationen war.
Beispiel: Erweitern von Konfigurationen
Beispielsweise führt der folgende Workflow vier Jobs aus, einen für jede Kombination von os
und node
. Wenn der Auftrag für den os
-Wert von windows-latest
und den node
-Wert von 16
ausgeführt wird, wird eine zusätzliche Variable namens npm
mit dem Wert 6
in den Auftrag einbezogen.
jobs:
example_matrix:
strategy:
matrix:
os: [windows-latest, ubuntu-latest]
node: [14, 16]
include:
- os: windows-latest
node: 16
npm: 6
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- if: ${{ matrix.npm }}
run: npm install -g npm@${{ matrix.npm }}
- run: npm --version
Beispiel: Hinzufügen von Konfigurationen
Diese Matrix führt beispielsweise zehn Aufträge aus, einen für jede Kombination von os
und version
in der Matrix sowie einen Auftrag für den Wert os
von windows-latest
und den Wert version
von 17
.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
Wenn du keine Matrixvariablen angibst, werden alle Konfigurationen unter include
ausgeführt. Der folgende Workflow würde beispielsweise zwei Aufträge ausführen, einen für jeden include
-Eintrag. Auf diese Weise kannst du die Matrixstrategie nutzen, ohne eine vollständig ausgefüllte Matrix zu haben.
jobs:
includes_only:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- site: "production"
datacenter: "site-a"
- site: "staging"
datacenter: "site-b"
jobs.<job_id>.strategy.matrix.exclude
Um bestimmte Konfigurationen zu entfernen, die in der Matrix definiert sind, verwende jobs.<job_id>.strategy.matrix.exclude
. Eine ausgeschlossene Konfiguration muss nur eine teilweise Übereinstimmung sein, damit sie ausgeschlossen werden kann. Der folgende Workflow führt z. B. neun Aufträge aus: ein Auftrag für jede der 12 Konfigurationen, minus der ausgeschlossenen Aufgabe, die mit {os: macos-latest, version: 12, environment: production}
übereinstimmt, und die beiden ausgeschlossenen Aufträge, die mit {os: windows-latest, version: 16}
übereinstimmen.
strategy:
matrix:
os: [macos-latest, windows-latest]
version: [12, 14, 16]
environment: [staging, production]
exclude:
- os: macos-latest
version: 12
environment: production
- os: windows-latest
version: 16
runs-on: ${{ matrix.os }}
Hinweis: Alle include
-Kombinationen werden nach exclude
verarbeitet. So kannst du mit include
wieder Kombinationen hinzufügen, die zuvor ausgeschlossen waren.
jobs.<job_id>.strategy.fail-fast
Du kannst steuern, wie Auftragsfehler mit jobs.<job_id>.strategy.fail-fast
und jobs.<job_id>.continue-on-error
verarbeitet werden.
jobs.<job_id>.strategy.fail-fast
gilt für die gesamte Matrix. Wenn jobs.<job_id>.strategy.fail-fast
auf true
festgelegt ist oder sein Ausdruck den Wert true
annimmt, bricht GitHub Enterprise 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
name: CI on: push: branches: [ main ] jobs: container-test-job: runs-on: ubuntu-latest container: image: node:18 env: NODE_ENV: development ports: - 80 volumes: - my_docker_volume:/volume_mount options: --cpus 1 steps: - name: Check for dockerenv file run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)
name: CI
on:
push:
branches: [ main ]
jobs:
container-test-job:
runs-on: ubuntu-latest
container:
image: node:18
env:
NODE_ENV: development
ports:
- 80
volumes:
- my_docker_volume:/volume_mount
options: --cpus 1
steps:
- name: Check for dockerenv file
run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)
Wenn du nur ein Containerimage angibst, kannst du das image
-Schlüsselwort weglassen.
jobs:
container-test-job:
runs-on: ubuntu-latest
container: node:18
jobs.<job_id>.container.image
Verwende jobs.<job_id>.container.image
, um das Docker-Image zu definieren, das beim Ausführen der Aktion als Container herangezogen wird. Der Wert kann der Name des Docker Hub-Images oder ein Registrierungsname sein.
jobs.<job_id>.container.credentials
Wenn die Containerregistrierung des Images eine Authentifizierung benötigt, damit das Image gepullt werden kann, kannst du mit jobs.<job_id>.container.credentials
eine map
von username
und password
festlegen. Die Anmeldeinformationen sind dieselben Werte, die du für den docker login
-Befehl angeben würdest.
Beispiel: Definieren der Anmeldeinformationen für eine Containerregistrierung
container:
image: ghcr.io/owner/image
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
jobs.<job_id>.container.env
Verwende jobs.<job_id>.container.env
, um eine map
von Umgebungsvariablen im Dienstcontainer einzustellen.
jobs.<job_id>.container.ports
Verwende jobs.<job_id>.container.ports
zum Festlegen eines array
aus Ports, die für den Container verfügbar gemacht werden sollen.
jobs.<job_id>.container.volumes
Verwende jobs.<job_id>.container.volumes
zum Festlegen eines array
von Volumes, die der Container verwenden soll. Mithilfe von Volumes kannst Du Daten zwischen Diensten oder anderen Schritten in einem Job austauschen. Du kannst benannte Docker-Volumes, anonyme Docker-Volumes oder Bind-Mounts auf dem Host angegeben.
Um ein Volume festzulegen, gibst du den Quell- und Zielpfad an:
<source>:<destinationPath>
.
<source>
ist ein Volumename oder ein absoluter Pfad auf dem Hostcomputer, und <destinationPath>
ist ein absoluter Pfad im Container.
Beispiel: Einbinden von Volumes in einem Container
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.container.options
Verwende jobs.<job_id>.container.options
zum Konfigurieren zusätzlicher Optionen für Docker-Containerressourcen. Eine Liste der Optionen findest du unter docker create
-Optionen.
Warnung: Die Optionen --network
und --entrypoint
werden nicht unterstützt.
jobs.<job_id>.services
Hinweis: Wenn deine Workflows Docker-Containeraktionen, Auftragscontainer oder Dienstcontainer verwenden, musst du einen Linux-Runner verwenden:
- Wenn du GitHub-gehostete Runner verwendest, musst du einen Ubuntu-Runner verwenden.
- Wenn du selbst gehostete Läufer verwendest, musst du einen Linux-Rechner als deinen Läufer verwenden und Docker muss installiert sein.
Wird zum Betrieb von Servicecontainern für einen Job in einem Workflow verwendet. Servicecontainer sind nützlich, um Datenbanken oder Cache-Dienste wie Redis zu erstellen. Der Runner erstellt automatisch ein Docker-Netzwerk und verwaltet den Lebenszyklus der Service-Container.
Wenn du deinen Auftrag so konfigurierst, dass er in einem Container ausgeführt wird, oder wenn dein Schritt Containeraktionen verwendet, brauchst du keine Ports zuzuordnen, um auf den Dienst oder die Aktion zuzugreifen. Docker öffnet automatisch alle Ports zwischen Containern im selben benutzerdefinierten Bridge-Netzwerk des Dockers. Du kannst den Servicecontainer direkt mit seinem Hostnamen referenzieren. Der Hostname wird automatisch dem Namen der Bezeichnung zugeordnet, die du für den Dienst im Workflow konfigurierst.
Wenn du den Auftrag so konfigurierst, dass er direkt auf dem Runnercomputer ausgeführt wird und dein Schritt keine Containeraktion verwendet, musst du alle erforderlichen Ports des Docker-Servicecontainers dem Docker-Host (dem Runnercomputer) zuordnen. Du kannst auf den Servicecontainer über localhost und den zugeordneten Port zugreifen.
Weitere Informationen zu den Unterschieden zwischen Netzwerkdienstcontainern findest du unter Informationen zu Service-Containern.
Beispiel: Verwenden des Localhosts
Dieses Beispiel erzeugt zwei Dienste: nginx und redis. Wenn Du den Port des Docker-Hosts angibst, aber nicht den des Containers, dann wird der Container-Port zufällig einem freien Port zugewiesen. GitHub legt den zugewiesenen Containerport im ${{job.services.<service_name>.ports}}
-Kontext fest. In diesem Beispiel kannst du mithilfe der Kontexte ${{ job.services.nginx.ports['8080'] }}
und ${{ job.services.redis.ports['6379'] }}
auf die Dienstcontainerports zugreifen.
services:
nginx:
image: nginx
# Map port 8080 on the Docker host to port 80 on the nginx container
ports:
- 8080:80
redis:
image: redis
# Map TCP port 6379 on Docker host to a random free port on the Redis container
ports:
- 6379/tcp
jobs.<job_id>.services.<service_id>.image
Docker-Image, das beim Ausführen der Aktion als Dienstcontainer herangezogen wird. Der Wert kann der Name des Docker Hub-Images oder ein Registrierungsname sein.
Wenn jobs.<job_id>.services.<service_id>.image
einer leeren Zeichenfolge zugewiesen ist, wird der Dienst nicht gestartet. Sie können dies verwenden, um bedingte Dienste einzurichten, ähnlich wie im folgenden Beispiel.
services:
nginx:
image: ${{ options.nginx == true && 'nginx' || '' }}
jobs.<job_id>.services.<service_id>.credentials
Wenn die Containerregistrierung des Images eine Authentifizierung benötigt, damit das Image gepullt werden kann, kannst du mit jobs.<job_id>.container.credentials
eine map
von username
und password
festlegen. Die Anmeldeinformationen sind dieselben Werte, die du für den docker login
-Befehl angeben würdest.
Beispiel für jobs.<job_id>.services.<service_id>.credentials
services:
myservice1:
image: ghcr.io/owner/myservice1
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
myservice2:
image: dockerhub_org/myservice2
credentials:
username: ${{ secrets.DOCKER_USER }}
password: ${{ secrets.DOCKER_PASSWORD }}
jobs.<job_id>.services.<service_id>.env
Hiermit wird eine map
von Umgebungsvariablen im Dienstcontainer festgelegt.
jobs.<job_id>.services.<service_id>.ports
Hiermit wird ein array
von Ports festgelegt, die auf dem Dienstcontainer verfügbar gemacht werden sollen.
jobs.<job_id>.services.<service_id>.volumes
Hiermit wird ein array
von Volumes festgelegt, die der Dienstcontainer verwenden soll. Mithilfe von Volumes kannst Du Daten zwischen Diensten oder anderen Schritten in einem Job austauschen. Du kannst benannte Docker-Volumes, anonyme Docker-Volumes oder Bind-Mounts auf dem Host angegeben.
Um ein Volume festzulegen, gibst du den Quell- und Zielpfad an:
<source>:<destinationPath>
.
<source>
ist ein Volumename oder ein absoluter Pfad auf dem Hostcomputer, und <destinationPath>
ist ein absoluter Pfad im Container.
Beispiel für jobs.<job_id>.services.<service_id>.volumes
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.services.<service_id>.options
Zusätzliche Optionen für die Docker-Container-Ressource. Eine Liste der Optionen findest du unter docker create
-Optionen.
Warnung: Die --network
-Option wird nicht unterstützt.
jobs.<job_id>.uses
Dies ist der Speicherort und die Version einer wiederverwendbaren Workflowdatei, die als Auftrag ausgeführt werden soll. Verwende eine der folgenden Syntaxen:
{owner}/{repo}/.github/workflows/{filename}@{ref}
für wiederverwendbare Workflows in öffentlichen, internen und privaten Repositorys../.github/workflows/{filename}
für wiederverwendbare Workflows im selben Repository.
Bei der ersten Option kann {ref}
ein SHA, ein Releasetag oder ein Branchname sein. Wenn ein Releasetag und ein Branch denselben Namen aufweisen, hat das Releasetag Vorrang vor dem Branchnamen. Die Verwendung des Commit-SHA-Werts ist die beste Option im Hinblick auf Stabilität und Sicherheit. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions.
Wenn du die zweite Syntaxoption verwendest (ohne {owner}/{repo}
und @{ref}
), stammt der aufgerufene Workflow aus demselben Commit wie der aufrufende Workflow. Verweispräfixe wie refs/heads
und refs/tags
sind nicht zulässig.
Beispiel für jobs.<job_id>.uses
jobs:
call-workflow-1-in-local-repo:
uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
call-workflow-2-in-local-repo:
uses: ./.github/workflows/workflow-2.yml
call-workflow-in-another-repo:
uses: octo-org/another-repo/.github/workflows/workflow.yml@v1
Weitere Informationen findest du unter Wiederverwenden von Workflows.
jobs.<job_id>.with
Wenn ein Auftrag zum Aufrufen eines wiederverwendbaren Workflows verwendet wird, kannst du mit with
eine Zuordnung von Eingaben bereitstellen, die an den aufgerufenen Workflow übergeben werden.
Alle Eingaben, die du übergibst, müssen den im aufgerufenen Workflow definierten Eingabespezifikationen entsprechen.
Im Gegensatz zu jobs.<job_id>.steps[*].with
sind die mit jobs.<job_id>.with
übergebenen Eingaben nicht als Umgebungsvariablen im aufgerufenen Workflow verfügbar. Stattdessen kannst du mithilfe des inputs
-Kontexts auf die Eingaben verweisen.
Beispiel für jobs.<job_id>.with
jobs:
call-workflow:
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
with:
username: mona
jobs.<job_id>.with.<input_id>
Dies ist ein aus einem Zeichenfolgenbezeichner für die Eingabe und dem Wert für die Eingabe bestehendes Paar. Der Bezeichner muss mit dem Namen der Eingabe übereinstimmen, die von on.workflow_call.inputs.<inputs_id>
im aufgerufenen Workflow definiert wird. Der Datentyp des Werts muss mit dem Typ übereinstimmen, der von on.workflow_call.inputs.<input_id>.type
im aufgerufenen Workflow definiert wird.
Zulässiger Ausdruckskontext: github
und needs
.
jobs.<job_id>.secrets
Wenn ein Auftrag zum Aufrufen eines wiederverwendbaren Workflows verwendet wird, kannst du mit secrets
eine Zuordnung von Geheimnissen bereitstellen, die an den aufgerufenen Workflow übergeben werden.
Alle Geheimnisse, die du übergibst, müssen mit den Namen übereinstimmen, die im aufgerufenen Workflow definiert sind.
Beispiel für jobs.<job_id>.secrets
jobs:
call-workflow:
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
secrets:
access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
jobs.<job_id>.secrets.inherit
Verwende das Schlüsselwort inherit
, um alle Geheimnisse des aufrufenden Workflows an den aufgerufenen Workflow zu übergeben. Dazu gehören alle Geheimnisse, auf die der aufrufende Workflow Zugriff hat, nämlich die Geheimnisse von Organisation, Repository und Umgebung. Das Schlüsselwort inherit
kann verwendet werden, um Geheimnisse zwischen Repositorys innerhalb derselben Organisation oder zwischen Organisationen innerhalb desselben Unternehmens zu übergeben.
Beispiel für jobs.<job_id>.secrets.inherit
on:
workflow_dispatch:
jobs:
pass-secrets-to-workflow:
uses: ./.github/workflows/called-workflow.yml
secrets: inherit
on:
workflow_call:
jobs:
pass-secret-to-action:
runs-on: ubuntu-latest
steps:
- name: Use a repo or org secret from the calling workflow.
run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}
jobs.<job_id>.secrets.<secret_id>
Dies ist ein aus einem Zeichenfolgenbezeichner für das Geheimnis und dem Wert für das Geheimnis bestehendes Paar. Der Bezeichner muss mit dem Namen eines Geheimnisses übereinstimmen, das von on.workflow_call.secrets.<secret_id>
im aufgerufenen Workflow definiert wird.
Zulässiger Ausdruckskontext: github
, needs
und secrets
.
Spickzettel für Filtermuster
In Pfad-, Branch- und Tagfiltern kannst du Sonderzeichen benutzen.
*
: Gleicht null oder mehr Zeichen ab, nicht jedoch das/
-Zeichen. Beispielsweise entsprichtOcto*``Octocat
.**
: Gleicht null oder mehr beliebige Zeichen ab.?
: Gleicht null oder eines der vorherigen Zeichen ab.+
: Gleicht eines oder mehrere der vorherigen Zeichen ab.[]
: Gleicht ein alphanumerisches Zeichen ab, das in Klammern aufgelistet oder in Bereichen enthalten ist. Bereiche können nura-z
,A-Z
und0-9
enthalten. Beispielsweise stimmt der Bereich[0-9a-z]
mit einer beliebigen Zahl oder einem Kleinbuchstaben überein.[CB]at
stimmt beispielsweise mitCat
oderBat
überein, und[1-2]00
stimmt mit100
und200
überein.!
: Wenn dies am Anfang eines Musters steht, negiert es vorherige positive Muster ins Gegenteil. Es hat keine besondere Bedeutung, wenn es nicht das erste Zeichen ist.
Die Zeichen *
, [
und !
sind Sonderzeichen in YAML. Wenn du ein Muster mit *
, [
oder !
beginnst, musst du das Muster in Anführungszeichen einschließen. Wenn du eine Ablaufsequenz mit einem Muster verwendest, das [
und/oder ]
enthält, muss das Muster zudem in Anführungszeichen gesetzt werden.
# Valid
paths:
- '**/README.md'
# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
- **/README.md
# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]
# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]
Weitere Informationen zur Syntax der Branch-, Tag- und Pfadfilter findest du unter on.<push>.<branches|tags>
, on.<pull_request>.<branches|tags>
und on.<push|pull_request>.paths
.
Muster für den Abgleich von Branches und Tags
Muster | BESCHREIBUNG | Beispiele 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.
Muster | Beschreibung der Übereinstimmungen | Beispiele 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/**/*.md | Dies 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 |