Skip to main content

Variablen

GitHub legt Standardvariablen für jede GitHub Actions-Workflowausführung fest. Du kannst auch benutzerdefinierte Variablen in deiner Workflowdatei festlegen.

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 Variablen

Du kannst Variablen verwenden, um Informationen zu speichern, auf die du in deinem Workflow verweisen möchtest. Der Verweis auf Variablen erfolgt innerhalb eines Workflowschritts oder einer Aktion, und die Variablen werden auf dem Runnercomputer interpoliert, auf dem der Workflow ausgeführt wird. Mit Befehlen, die in Aktionen oder Workflowschritten ausgeführt werden, können Variablen erstellt, gelesen oder geändert werden.

Du kannst deine eigenen benutzerdefinierten Variablen festlegen oder die Standardvariablen verwenden, die GitHub automatisch festlegt, aber auch alle anderen Variablen, die in der Arbeitsumgebung auf dem Runner festgelegt sind. Bei Variablen wird die Groß- und Kleinschreibung beachtet.

Definieren von Umgebungsvariablen

Um eine benutzerdefinierte Umgebungsvariable festzulegen, kannst du sie mithilfe des env-Schlüssels in der Workflowdatei definieren. Der Geltungsbereich einer mit dieser Methode festgelegten benutzerdefinierten Variable ist auf das Element beschränkt, in dem sie definiert wird. Du kannst Variablen definieren, die für Folgendes gelten:

  • Den gesamten Workflow, indem du in der Workflowdatei auf der obersten Ebene env verwendest
  • Den Inhalt eines Auftrags in einem Workflow, indem du jobs.<job_id>.env verwendest
  • Einen bestimmten Schritt innerhalb eines Auftrags, indem du jobs.<job_id>.steps[*].env verwendest
name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Du kannst auf env-Variablenwerte mithilfe von Runnerumgebungsvariablen oder mithilfe von Kontexten zugreifen. Im obigen Beispiel siehst du drei benutzerdefinierte Variablen, die in einem echo-Befehl als Umgebungsvariablen verwendet werden: $DAY_OF_WEEK, $Greeting und $First_Name. Die Werte für diese Variablen werden auf Workflow-, Auftrags- und Schrittebene festgelegt, und ihr Geltungsbereich wird entsprechend beschränkt. Weitere Informationen zum Zugreifen auf Variablenwerte mithilfe von Kontexten findest du unter Verwenden von Kontexten für den Zugriff auf Variablenwerte.

Da die Interpolation der Runnerumgebungsvariablen nach dem Senden eines Workflowauftrags an einen Runnercomputer durchgeführt wird, musst du die richtige Syntax für die auf dem Runner verwendete Shell verwenden. In diesem Beispiel ist im Workflow ubuntu-latest angegeben. Auf Linux-Runnern wird standardmäßig die Bash-Shell verwendet. Daher musst du in diesem Fall die Syntax $NAME verwenden. Wenn im Workflow ein Windows-Runner angegeben ist, verwende die Syntax für PowerShell: $env:NAME. Weitere Informationen zu Shells findest du unter Workflowsyntax für GitHub Actions.

Namens-Konventionen für Umgebungsvariablen

Wenn du eine Umgebungsvariable festlegst, kannst du nicht die Namen von Standardumgebungsvariablen verwenden. Eine vollständige Liste dieser Standardumgebungsvariablen findest du weiter unten unter Standardumgebungsvariablen. Wenn du versuchst, den Wert einer dieser Standardvariablen zu überschreiben, wird diese Zuweisung ignoriert.

Alle neuen, von dir festgelegten Variablen, die auf einen Ort im Dateisystem verweisen, müssen über die Endung _PATH verfügen. Die Standardvariablen GITHUB_ENV und GITHUB_WORKSPACE sind von dieser Konvention ausgenommen.

Hinweis: Du kannst alle für einen Workflowschritt verfügbaren Umgebungsvariablen auflisten, indem du in einem Schritt run: env verwendest und dann die Ausgabe für diesen Schritt untersuchst.

Verwenden von Kontexten für den Zugriff auf die Werte von Variablen

Kontexte sind eine Möglichkeit, auf Informationen zu Workflowausführungen, Variablen, Runnerumgebungen, Aufträge und Schritten zuzugreifen. Weitere Informationen findest du unter Kontexte. Es gibt noch viele weitere Kontexte, die du für verschiedene Zwecke in deinen Workflows verwenden kannst. Ausführliche Informationen dazu, wo du bestimmte Kontexte innerhalb eines Workflows verwenden kannst, findest du unter Kontextverfügbarkeit.

Du kannst mithilfe des env-Kontexts auf Konfigurationsvariablenwerte zugreifen.

Verwenden des env-Kontexts für den Zugriff auf die Werte von Umgebungsvariablen

Neben Runnerumgebungsvariablen kannst du mit GitHub Actions mithilfe von Kontexten auch env-Schlüsselwerte festlegen und lesen. Umgebungsvariablen und Kontexte sind für verschiedene Stellen im Workflow vorgesehen.

Runnerumgebungsvariablen werden immer auf dem Runnercomputer interpoliert. Teile eines Workflows werden jedoch von GitHub Actions verarbeitet und nicht an den Runner gesendet. In diesen Teilen einer Workflowdatei können keine Umgebungsvariablen verwendet werden. Stattdessen kannst du Kontexte verwenden. Eine if-Bedingung, mit der entschieden wird, ob ein Auftrag oder Schritt an den Runner gesendet wird, wird beispielsweise immer von GitHub Actions verarbeitet. In if-Bedingungsanweisungen kannst du Kontexte verwenden, um auf die Werte von Variablen zuzugreifen.

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Monday' }}
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

In dieser abgewandelten Version des vorherigen Beispiels wurde eine if-Bedingung ergänzt. Der Workflowschritt wird jetzt nur ausgeführt, wenn DAYS_OF_WEEK auf „Monday“ festgelegt ist. In der if-Bedingungsanweisung wird auf diesen Wert über den Kontext env zugegriffen.

Hinweis: Kontexte werden in der Regel mit einem Dollarzeichen und geschweiften Klammern gekennzeichnet, z. B. ${{ context.property }}. In einer if-Bedingung sind ${{ und }} optional. Wenn du diese Zeichen verwendest, müssen sie jedoch die gesamte Vergleichsanweisung umschließen, wie oben zu sehen.

Oft wirst du entweder den Kontext env oder github verwenden, um auf Werte von Variablen in Teilen des Workflows zuzugreifen, die verarbeitet werden, bevor Aufträge an Runner gesendet werden.

KontextAnwendungsfallBeispiel
envVerweisen auf benutzerdefinierte Variablen, die im Workflow definiert sind${{ env.MY_VARIABLE }}
githubVerweisen auf Informationen zur Workflowausführung und zu dem Ereignis, durch das die Ausführung ausgelöst wurde${{ github.repository }}

Standardumgebungsvariablen

Die von GitHub festgelegten Standardumgebungsvariablen sind in jedem Schritt eines Workflows verfügbar.

Es wird dringend empfohlen, die Aktionen mithilfe von Variablen auf das Dateisystem zugreifen zu lassen statt über hartkodierte Dateipfade. GitHub legt Variablen für Aktionen fest, die in allen Runnerumgebungen verwendet werden sollen.

VariableBESCHREIBUNG
CIImmer auf true festgelegt.
GITHUB_ACTIONName der aktuell ausgeführten Aktion oder der id-Wert eines Schritts. Ein Beispiel für eine Aktion wäre __repo-owner_name-of-action-repo.

GitHub entfernt Sonderzeichen und verwendet den Namen __run, wenn der aktuelle Schritt ein Skript ohne id ausführt. Wenn du ein Skript oder eine Aktion in einem Auftrag mehrmals verwendest, enthält der Name ein Suffix, das aus einem Unterstrich, gefolgt von einer laufenden Nummer, besteht. So lautet z. B. der Name des ersten Skripts, das du ausführst, __run und der des zweiten __run_2. Analog dazu erhält der zweite Aufruf von actions/checkout den Namen actionscheckout2.
GITHUB_ACTION_PATHPfad einer Aktion. Diese Eigenschaft wird nur in zusammengesetzten Aktionen unterstützt. Mit diesem Pfad kannst du auf Dateien zugreifen, die sich im selben Repository wie die Aktion befinden. Beispiel: /home/runner/work/_actions/repo-owner/name-of-action-repo/v1.
GITHUB_ACTION_REPOSITORYBei einem Schritt, in dem eine Aktion ausgeführt wird, gibt diese Eigenschaft den Namen des Besitzers bzw. der Besitzerin und des Repositorys der Aktion an. Beispiel: actions/checkout.
GITHUB_ACTIONSWenn GitHub Actions den Workflow ausführt, ist der Wert dieser Variable immer auf true festgelegt. Du kannst diese Variable verwenden, um zu differenzieren, wann Tests lokal oder von GitHub Actions durchgeführt werden.
GITHUB_ACTORName der Person oder App, die den Workflow initiiert hat. Beispiel: octocat.
GITHUB_BASE_REFName des Basisverweises oder Zielbranchs des Pull Requests in einer Workflowausführung. Diese Variable wird nur festgelegt, wenn das Ereignis, durch das eine Workflowausführung ausgelöst wird, entweder pull_request oder pull_request_target ist. Beispiel: main.
GITHUB_HEAD_REFVerweis auf den Hauptbranch oder der Quellbranch des Pull Requests in einer Workflowausführung. Diese Eigenschaft wird nur festgelegt, wenn das Ereignis, durch das eine Workflowausführung ausgelöst wird, entweder pull_request oder pull_request_target ist. Beispiel: feature-branch-1.
GITHUB_SHADer Commit-SHA-Wert, der den Workflow ausgelöst hat. Dieser Wert hängt von dem Ereignis ab, das den Workflow ausgelöst hat. Weitere Informationen findest du unter Ereignisse, die Workflows auslösen. Beispiel: ffac537e6cbbf934b08745a378932722df287a53.

Hinweis:

  • Wenn du die URL einer Workflowausführung in einem Auftrag verwenden musst, kannst du diese Variablen kombinieren: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID.
  • Die meisten Standardvariablen verfügen über eine entsprechende Kontexteigenschaft mit einem ähnlichen Namen. So kann beispielsweise der Wert der Variable GITHUB_REF während der Workflowverarbeitung mit der Kontexteigenschaft ${{ github.ref }} gelesen werden.

Erkennen des Betriebssystems

Mithilfe der Standardumgebungsvariable RUNNER_OS und der entsprechenden Kontexteigenschaft ${{ runner.os }} kannst du eine einzelne Workflowdatei erstellen, die für verschiedene Betriebssysteme verwendet werden kann. Beispielsweise könnte der folgende Workflow erfolgreich ausgeführt werden, wenn du das Betriebssystem von macos-latest in windows-latest änderst, ohne dass die Syntax der Umgebungsvariablen angepasst werden muss, die je nachdem, welche Shell auf dem Runner verwendet wird, unterschiedlich ist.

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

In diesem Beispiel wird mit den beiden if-Anweisungen die Eigenschaft os des Kontexts runner überprüft, um das Betriebssystem des Runners zu ermitteln. Die if-Bedingungen werden von GitHub Actions verarbeitet, und nur Schritte, in denen das Ergebnis der Überprüfung true lautet, werden an den Runner gesendet. Hier ist immer das Ergebnis einer Überprüfung true und das der anderen false, sodass nur einer dieser Schritte an den Runner gesendet wird. Sobald der Auftrag an den Runner gesendet wird, wird der Schritt ausgeführt, und die Umgebungsvariable im echo-Befehl wird mit der richtigen Syntax interpoliert ($env:NAME für PowerShell unter Windows und $NAME für Bash und sh unter Linux bzw. macOS). In diesem Beispiel bedeutet die Anweisung runs-on: macos-latest, dass der zweite Schritt ausgeführt wird.

Übergeben von Werten zwischen Schritten und Aufträgen in einem Workflow

Wenn ein Wert in einem Schritt eines Auftrags generiert wird, kannst du diesen in darauffolgenden Schritten desselben Auftrags verwenden, indem du den Wert einer bereits vorhandenen oder neuen Umgebungsvariable zuweist und diese dann in die GITHUB_ENV-Umgebungsdatei schreibst. Die Umgebungsdatei kann direkt von einer Aktion oder über einen Shellbefehl in der Workflowdatei mit dem Schlüsselwort run verwendet werden. Weitere Informationen findest du unter Workflowbefehle für GitHub Actions.

Wenn du einen Wert von einem Schritt in einem Auftrag in einem bestimmten Workflow an einen Schritt in einem anderen Auftrag in diesem Workflow übergeben möchtest, kannst du den Wert als Auftragsausgabe definieren. Dann kannst du in einem Schritt in einem anderen Auftrag auf diese Auftragsausgabe verweisen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.