Auswerten von Ausdrücken in Workflows und Aktionen

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 Zugreifen auf kontextbezogene Informationen zu Workflowausführungen.

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

Beispiel zum Setzen einer Umgebungsvariablen

env:
  MY_ENV_VAR: ${{ <expression> }}

Literale

In Ausdrücken kannst du die Datentypen boolean, null, number oder string verwenden.

Beachten Sie, dass in Bedingungen falsche Werte (false, 0, -0, "", '', null) zu false gezwungen werden und wahre Werte (true und andere nicht falsche Werte) zu truegezwungen werden.

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

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 gibt 1 zurück. false gibt 0 zurück.
  String	Aus einem zulässigem JSON-Zahlenformat geparst, andernfalls NaN. Hinweis: Eine leere Zeichenfolge gibt 0 zurück.
  Array	NaN
  Objekt	NaN

• Wenn NaN einer der Operanden eines relationalen Vergleichs (>, <, >=, <=) ist, ist das Ergebnis immer false. 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.

GitHub bietet ein ternäres Operatorverhalten, das du in Ausdrücken verwenden kannst. Wenn du einen ternären Operator auf diese Weise verwendest, kannst du den Wert einer Umgebungsvariablen basierend auf einer Bedingung dynamisch festlegen, ohne separate if-else-Blöcke für jede mögliche Option schreiben zu müssen.

Beispiel

env:
  MY_ENV_VAR: ${{ github.ref == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }}

In diesem Beispiel verwenden wir einen ternären Operator, um den Wert der Umgebungsvariablen MY_ENV_VAR basierend darauf festzulegen, ob der GitHub-Verweis auf refs/heads/main festgelegt ist oder nicht. Wenn dies der Fall ist, ist die Variable auf value_for_main_branch festgelegt. Andernfalls ist sie auf value_for_other_branches festgelegt. Es ist wichtig zu beachten, dass der erste Wert nach dem && wahr sein muss. Andernfalls wird der Wert nach dem || immer zurückgegeben.

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:

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. Sie können diese Funktion verwenden, um ein JSON-Objekt als ausgewerteten Ausdruck bereitzustellen oder einen beliebigen Datentyp zu konvertieren, der in JSON oder JavaScript dargestellt werden kann, z. B. Zeichenfolgen, boolesche Werte, Nullwerte, Arrays und Objekte.

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 "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

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

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

Der Workflow verwendet die Funktion fromJSON(), um die Umgebungsvariable continue aus einer Zeichenfolge in einen booleschen Wert zu konvertieren, sodass sie bestimmen kann, ob der Vorgang fortgesetzt werden soll oder nicht. Ebenso konvertiert sie die Umgebungsvariable time von einer Zeichenfolge in eine ganze Zahl, wobei das Timeout für den Auftrag in Minuten festgelegt wird.

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. Der Musterabgleich für hashFiles entspricht dem Globmusterabgleich und unter Windows wird die Groß-/Kleinschreibung nicht beachtet. Weitere Informationen zu den unterstützten Zeichen für den Musterabgleich sind im Abschnitt Muster in der @actions/glob-Dokumentation zu finden.

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 alle vorherigen Schritte erfolgreich waren.

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.

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.