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 zu Ausdrücken
Mit Ausdrücken kannst du programmgesteuert Variablen in Workflow-Dateien festlegen und auf Kontexte zugreifen. Ein Ausdruck kann eine beliebige Kombination aus literalen Werten, Verweisen auf einen Kontext und Funktionen sein. Du kannst Literale, Kontextverweise und Funktionen mithilfe von Operatoren kombinieren. Weitere Informationen zu Kontexten findest du unter Kontexte.
Ausdrücke werden in Workflowdateien häufig mit dem Bedingungsschlüsselwort if
verwendet, um festzulegen, ob ein Schritt ausgeführt werden soll. Wenn eine if
-Bedingung true
ist, wird der Schritt ausgeführt.
Du musst eine spezielle Syntax verwenden, um GitHub mitzuteilen, dass ein Ausdruck nicht als Zeichenfolge behandelt, sondern ausgewertet werden soll.
${{ <expression> }}
Wenn du Ausdrücke in einer if
-Bedingung verwendest, kannst du die Syntax des Ausdrucks (${{ }}
) weglassen, weil GitHub automatisch die if
-Bedingung als Ausdruck wertet. Weitere Informationen zu if
-Bedingungen findest du unter Workflowsyntax für GitHub Actions.
Warnung: Beim Erstellen von Workflows und Aktionen solltest du immer überprüfen, ob dein Code gegebenenfalls nicht vertrauenswürdige Eingaben von Angreifern ausführen kann. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions.
Beispielausdruck in einer if
-Bedingung
steps:
- uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
if: ${{ <expression> }}
Beispiel zum Setzen einer Umgebungsvariablen
env:
MY_ENV_VAR: ${{ <expression> }}
Literale
In Ausdrücken kannst du die Datentypen boolean
, null
, number
oder string
verwenden.
Datentyp | Literalwert |
---|---|
boolean | true oder false |
null | null |
number | Alle von JSON unterstützten Zahlenformate |
string | Du musst Zeichenfolgen nicht mit ${{ und }} umschließen. Wenn du dich jedoch dazu entscheidest, musst du die Zeichenfolge mit einfachen Anführungszeichen (' ) umschließen. Wenn du ein einzelnes Anführungszeichen als Literal verwenden möchtest, musst du ein zusätzliches einzelnes Anführungszeichen ('' ) als Escapezeichen verwenden. Das Umschließen mit doppelten Anführungszeichen (" ) löst einen Fehler aus. |
Beispiel für Literale
env:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99e-2 }}
myString: Mona the Octocat
myStringInBraces: ${{ 'It''s open source!' }}
Operatoren
Operator | BESCHREIBUNG |
---|---|
( ) | Logische Gruppierung |
[ ] | Index |
. | Eigenschaftsdereferenzierung |
! | Not |
< | Kleiner als |
<= | Kleiner als oder gleich |
> | Größer als |
>= | Größer als oder gleich |
== | Gleich |
!= | Ungleich |
&& | And |
|| | oder |
GitHub vergleicht auf Gleichheit in toleranter Weise.
-
Wenn die Typen nicht übereinstimmen, wandelt GitHub den Typ in eine Zahl um. GitHub übergibt Datentypen anhand der folgenden Umwandlungen an eine Zahl:
type Ergebnis Null 0
Boolean true
gibt1
zurück.
false
gibt0
zurück.String Aus einem zulässigem JSON-Zahlenformat geparst, andernfalls NaN
.
Hinweis: Eine leere Zeichenfolge gibt0
zurück.Array NaN
Object NaN
-
Ein Vergleich eines
NaN
-Werts mit einem anderenNaN
-Wert ergibt nichttrue
. Weitere Informationen findest du unter Mozilla-Dokumentation zu NaN-Werten. -
GitHub ignoriert beim Vergleichen der Strings die Groß- und Kleinschreibung.
-
Objekte und Arrays werden nur dann als gleich betrachtet, wenn sie dieselbe Instanz sind.
Functions
GitHub bietet integrierte Funktionen, die du in Ausdrücken verwenden kannst. Manche Funktionen verwandeln Werte an einen String, um Vergleiche durchzuführen. GitHub verwandelt Daten verschiedener Typen folgendermaßen in einen String:
type | Ergebnis |
---|---|
Null | '' |
Boolean | 'true' oder 'false' |
Number | Dezimalformat, bei großen Zahlen exponentiell |
Array | Arrays werden nicht in einen String umgewandelt. |
Object | Objekte werden nicht in einen String umgewandelt. |
contains
contains( search, item )
Gibt true
zurück, wenn search``item
enthält. Wenn search
ein Array ist, gibt diese Funktion true
zurück, wenn es sich bei item
um ein Arrayelement handelt. Wenn search
einer Zeichenfolge entspricht, gibt diese Funktion true
zurück, wenn es sich bei item
um eine Unterzeichenfolge von search
handelt. Bei dieser Funktion wird die Groß- und Kleinschreibung nicht berücksichtigt. Wandelt Werte in einen String um.
Beispiel mit einem String
true
gibt contains('Hello world', 'llo')
zurück.
Beispiel für die Verwendung eines Objektfilters
contains(github.event.issue.labels.*.name, 'bug')
gibt true
zurück, wenn das Issue im Zusammenhang mit dem Ereignis als Fehler (bug) bezeichnet wird.
Weitere Informationen findest du unter Objektfilter.
Beispiel für den Abgleich eines Arrays aus Zeichenfolgen
Anstatt github.event_name == "push" || github.event_name == "pull_request"
zu schreiben, kannst du contains()
mit fromJSON()
verwenden, um zu überprüfen, ob ein Array aus Zeichenfolgen ein item
enthält.
contains(fromJSON('["push", "pull_request"]'), github.event_name)
gibt beispielsweise true
zurück, wenn github.event_name
„push“ oder „pull_request“ lautet.
startsWith
startsWith( searchString, searchValue )
Gibt true
zurück, wenn searchString
mit searchValue
beginnt. Bei dieser Funktion wird die Groß- und Kleinschreibung nicht berücksichtigt. Wandelt Werte in einen String um.
Beispiel für startsWith
true
gibt startsWith('Hello world', 'He')
zurück.
endsWith
endsWith( searchString, searchValue )
Gibt true
zurück, wenn searchString
mit searchValue
endet. Bei dieser Funktion wird die Groß- und Kleinschreibung nicht berücksichtigt. Wandelt Werte in einen String um.
Beispiel für endsWith
true
gibt endsWith('Hello world', 'ld')
zurück.
format
format( string, replaceValue0, replaceValue1, ..., replaceValueN)
Ersetzt Werte in der Zeichenfolge (string
) durch die Variable replaceValueN
. Variablen in string
werden mit der {N}
-Syntax angegeben, wobei es sich bei N
um eine ganze Zahl handelt. Du musst mindestens einen replaceValue
- und einen string
-Wert angeben. Es gibt kein Maximum für die Anzahl der Variablen (replaceValueN
), die du verwenden kannst. Verwende geschweifte Klammern doppelt, um eine als Escapezeichen zu verwenden.
Beispiel für format
format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')
Gibt „Hello Mona the Octocat“ zurück
Beispiel mit maskierten Klammern
format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat')
Gibt „{Hello Mona the Octocat!}“ zurück
join
join( array, optionalSeparator )
Der Wert von array
kann ein Array oder eine Zeichenfolge sein. Alle Werte im array
sind zu einer Zeichenfolge verkettet. Wenn du optionalSeparator
angibst, wird der Wert in die verketteten Werte eingefügt. Andernfalls wird das Standardtrennzeichen ,
verwendet. Wandelt Werte in einen String um.
Beispiel für join
join(github.event.issue.labels.*.name, ', ')
kann 'bug, help wanted' (Fehler, Hilfe benötigt) zurückgeben.
toJSON
toJSON(value)
Gibt eine Pretty-Print-JSON-Darstellung von value
zurück. Diese Funktion hilft Dir bei der Fehlersuche in den Informationen, die in Kontexten enthalten sind.
Beispiel für toJSON
toJSON(job)
kann { "status": "success" }
zurückgeben.
fromJSON
fromJSON(value)
Gibt ein JSON-Objekt oder einen JSON-Datentyp für value
zurück. Mit dieser Funktion kannst du JSON-Objekte als ausgewertete Ausdrücke bereitstellen oder Umgebungsvariablen aus einer Zeichenfolge konvertieren.
Beispiel für die Rückgabe eines JSON-Objekts
Dieser Workflow legt eine JSON-Matrix in einem Auftrag fest und übergibt sie mit einer Ausgabe und fromJSON
an den nächsten Auftrag.
name: build
on: push
jobs:
job1:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- id: set-matrix
run: echo "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"
job2:
needs: job1
runs-on: ubuntu-latest
strategy:
matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
steps:
- run: build
Beispiel für die Rückgabe eines JSON-Datentyps
Dieser Workflow konvertiert Umgebungsvariablen mithilfe von fromJSON
von einer Zeichenfolge in eine boolesche oder eine ganze Zahl.
name: print
on: push
env:
continue: true
time: 3
jobs:
job1:
runs-on: ubuntu-latest
steps:
- continue-on-error: ${{ fromJSON(env.continue) }}
timeout-minutes: ${{ fromJSON(env.time) }}
run: echo ...
hashFiles
hashFiles(path)
Gibt einen einzelnen Hash für Dateien zurück, die dem path
-Muster entsprechen. Du kannst ein einzelnes path
-Muster oder mehrere path
-Muster bereitstellen, die durch Kommas getrennt sind. path
ist relativ zum GITHUB_WORKSPACE
-Verzeichnis und kann nur Dateien innerhalb des GITHUB_WORKSPACE
-Verzeichnisses enthalten. Diese Funktion berechnet einen individuellen SHA-256-Hash für jede passende Datei und verwendet diese Hashes dann zur Berechnung eines endgültigen SHA-256-Hashs für den Satz von Dateien. Wenn das path
-Muster keinen Dateien entspricht, gibt es eine leere Zeichenfolge zurück. Weitere Informationen zu SHA-256 findest du unter SHA-2.
Du kannst Zeichen zum Musterabgleich verwenden, um Dateien mit passenden Namen auszuwählen. Bei dem Musterabgleich unter Windows wird die Groß-/Kleinschreibung nicht beachtet. Weitere Informationen zu unterstützten Musterabgleichszeichen findest du unter Workflowsyntax für GitHub Actions.
Beispiel für ein einzelnes Muster
Stimmt mit allen package-lock.json
-Dateien im Repository überein
hashFiles('**/package-lock.json')
Beispiel mit mehreren Mustern
Erstellt einen Hash für alle package-lock.json
- und Gemfile.lock
-Dateien im Repository
hashFiles('**/package-lock.json', '**/Gemfile.lock')
Statusprüfungsfunktionen
Du kannst die nachfolgenden Statusüberprüfungsfunktionen als Ausdrücke in if
-Bedingungen verwenden. Eine Standardstatusprüfung von success()
wird angewendet, sofern du keine dieser Funktionen einfügst. Weitere Informationen zu if
-Bedingungen findest du unter Workflowsyntax für GitHub Actions und Metadatensyntax für GitHub Actions.
success
Gibt true
zurück, wenn keiner der vorherigen Schritte fehlgeschlagen ist oder abgebrochen wurde
Beispiel für success
steps:
...
- name: The job has succeeded
if: ${{ success() }}
immer
Bewirkt, dass der Schritt immer ausgeführt wird, und gibt selbst bei Abbruch true
zurück Der always
-Ausdruck wird am besten auf der Schrittebene oder für Aufgaben verwendet, die du voraussichtlich ausführst, auch wenn ein Auftrag abgebrochen wird. Du kannst beispielsweise always
verwenden, um Protokolle zu senden, auch wenn ein Auftrag abgebrochen wird.
Hinweis: Vermeide die Verwendung von always
für eine Aufgabe, bei der ein kritischer Fehler auftreten könnte, z. B. beim Abrufen von Quellen. Andernfalls bleibt der Workflow möglicherweise bis zum Auftreten eines Timeouts hängen. Wenn du einen Auftrag oder Schritt unabhängig vom Erfolg oder Fehler ausführen möchtest, verwende die empfohlene Alternative:if: success() || failure()
Beispiel für always
if: ${{ always() }}
cancelled
Gibt true
zurück, wenn der Workflow abgebrochen wurde
Beispiel für cancelled
if: ${{ cancelled() }}
failure
Gibt true
zurück, wenn ein vorheriger Schritt eines Auftrags fehlschlägt. Wenn du über eine Kette abhängiger Aufträge verfügst, gibt failure()
true
zurück, wenn ein vorheriger Auftrag fehlschlägt.
Beispiel für failure
steps:
...
- name: The job has failed
if: ${{ failure() }}
Fehler bei Bedingungen
Du kannst zusätzliche Bedingungen für einen Schritt einschließen, der nach einem Fehler ausgeführt werden soll. Allerdings musst du dennoch failure()
einfügen, um die Standardstatusüberprüfung für success()
außer Kraft zu setzen, die automatisch auf if
-Bedingungen angewendet wird, die keine Statusprüfungsfunktion enthalten.
Beispiel für failure
mit Bedingungen
steps:
...
- name: Failing step
id: demo
run: exit 1
- name: The demo step has failed
if: ${{ failure() && steps.demo.conclusion == 'failure' }}
Objektfilter
Mit der *
-Syntax kannst du einen Filter anwenden und übereinstimmende Elemente in einer Sammlung auswählen.
Als Beispiel sei das Objektarray namens fruits
gegeben.
[
{ "name": "apple", "quantity": 1 },
{ "name": "orange", "quantity": 2 },
{ "name": "pear", "quantity": 1 }
]
Der Filter fruits.*.name
gibt das Array [ "apple", "orange", "pear" ]
zurück.
Du kannst auch die *
-Syntax für ein Objekt verwenden. Angenommen, du verfügst über ein Objekt namens vegetables
.
{
"scallions":
{
"colors": ["green", "white", "red"],
"ediblePortions": ["roots", "stalks"],
},
"beets":
{
"colors": ["purple", "red", "gold", "white", "pink"],
"ediblePortions": ["roots", "stems", "leaves"],
},
"artichokes":
{
"colors": ["green", "purple", "red", "black"],
"ediblePortions": ["hearts", "stems", "leaves"],
},
}
Der Filter vegetables.*.ediblePortions
kann wie folgt ausgewertet werden:
[
["roots", "stalks"],
["hearts", "stems", "leaves"],
["roots", "stems", "leaves"],
]
Da Objekte keine Reihenfolge beibehalten, kann die Reihenfolge der Ausgabe nicht garantiert werden.