Skip to main content

Variablen

GitHub legt Standardvariablen für jede GitHub Actions-Workflowausführung fest. Du kannst auch benutzerdefinierte Variablen für die Verwendung in einem einzelnen oder mehreren Workflows festlegen.

Informationen zu Variablen

Variablen bieten die Möglichkeit, nicht vertrauliche Konfigurationsinformationen zu speichern und wiederzuverwenden. Du kannst beliebige Konfigurationsdaten wie Compilerflags, Benutzernamen oder Servernamen als Variablen speichern. Variablen werden auf dem Runnercomputer interpoliert, auf dem dein 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 eigene benutzerdefinierten Variablen festlegen oder die Standardumgebungsvariablen verwenden, die GitHub automatisch festlegt. Weitere Informationen findest du unter Standardumgebungsvariablen.

Du kannst eine benutzerdefinierte Variable auf zwei Arten festlegen.

Warnung: Standardmäßig werden Variablen in deinen Buildausgaben unmaskiert gerendert. Wenn du mehr Sicherheit für vertrauliche Informationen benötigst (z. B. Kennwörter), verwende stattdessen verschlüsselte Geheimnisse. Weitere Informationen findest du unter Verschlüsselte Geheimnisse.

Definieren von Umgebungsvariablen für einen einzelnen Workflow

Um eine benutzerdefinierte Umgebungsvariable für einen einzelnen Workflow 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.

Definieren von Konfigurationsvariablen für mehrere Workflows

Hinweis: Konfigurationsvariablen für GitHub Actions befinden sich in der Betaphase und können geändert werden.

Du kannst Konfigurationsvariablen für mehrere Workflows erstellen und diese entweder auf Organisations-, Repository- oder Umgebungsebene definieren.

Du kannst beispielsweise Konfigurationsvariablen verwenden, um Standardwerte für Parameter festzulegen, die an Buildtools auf Organisationsebene übergeben werden, und Repositorybesitzern dann erlauben, diese Parameter von Fall zu Fall zu überschreiben.

Wenn du Konfigurationsvariablen definierst, sind sie automatisch im vars-Kontext verfügbar. Weitere Informationen findest du unter Verwenden des Kontexts vars für den Zugriff auf Werte von Konfigurationsvariablen.

Rangfolge der Konfigurationsvariablen

Wenn eine Variable mit demselben Namen auf mehreren Ebenen vorhanden ist, erhält die Variable auf der niedrigsten Ebene Vorrang. Wenn beispielsweise eine Variable auf Organisationsebene denselben Namen wie eine Variable auf Repositoryebene aufweist, erhält die Variable auf Repositoryebene Vorrang. Analog dazu hat bei einer Variable mit demselben Namen in einer Organisation, einem Repository und einer Umgebung die Variable auf Umgebungsebene Vorrang.

Für wiederverwendbare Workflows werden die Variablen aus dem Repository des Aufrufers verwendet. Variablen aus dem Repository, das den aufgerufenen Workflow enthält, werden dem Aufruferworkflow nicht zur Verfügung gestellt.

Benennungskonventionen für Konfigurationsvariablen

Für Namen von Konfigurationsvariablen gelten folgende Regeln:

  • Namen dürfen nur alphanumerische Zeichen ([a-z], [A-Z], [0-9]) oder Unterstriche (_) enthalten. Leerzeichen sind nicht zulässig.
  • Namen dürfen nicht mit dem Präfix GITHUB_ beginnen.
  • Namen dürfen nicht mit einer Ziffer beginnen.
  • Bei Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  • Namen müssen auf der Ebene eindeutig sein, auf der sie erstellt werden.

Erstellen von Konfigurationsvariablen für ein Repository

Um Geheimnisse oder Variablen für ein persönliches Kontorepository zu erstellen, musst du Repositorybesitzer*in sein. Um Geheimnisse oder Variablen für ein Organisationsrepository zu erstellen, musst du über admin-Zugriff verfügen.

  1. Navigiere auf GitHub.com zur Hauptseite des Repositorys. 1. Klicke unter dem Repositorynamen auf Einstellungen. Schaltfläche „Repositoryeinstellungen“ 1. Wähle im Abschnitt Sicherheit der Randleiste Geheimnisse und Variablen, und klicke dann auf Aktionen. 1. Klicke auf die Registerkarte Variablen. Registerkarte „Repositoryvariablen“
  2. Klicke auf Neue Repositoryvariable.
  3. Gib im Feld Name einen Namen für deine Variable ein.
  4. Gib im Feld Wert den Wert für deine Variable ein.
  5. Klicke auf Variable hinzufügen.

Erstellen von Konfigurationsvariablen für eine Umgebung

Um Geheimnisse oder Variablen für eine Umgebung in einem persönlichen Kontorepository zu erstellen, musst du Repositorybesitzer*in sein. Um Geheimnisse oder Variablen für eine Umgebung in einem Organisationsrepository zu erstellen, musst du über admin-Zugriff verfügen.

  1. Navigiere auf GitHub.com zur Hauptseite des Repositorys. 1. Klicke unter dem Repositorynamen auf Einstellungen. Schaltfläche „Repositoryeinstellungen“ 1. Klicke auf der linken Randleiste auf Umgebungen.
  2. Klicke auf die Umgebung, der du eine Variable hinzufügen möchtest.
  3. Klicke unter Umgebungsvariablen auf Variable hinzufügen.
  4. Gib im Feld Name einen Namen für deine Variable ein.
  5. Gib im Feld Wert den Wert für deine Variable ein.
  6. Klicke auf Variable hinzufügen.

Erstellen von Konfigurationsvariablen für eine Organisation

Beim Erstellen eines Geheimnisses oder einer Variable in einer Organisation kannst du mit einer Richtlinie den Zugriff jeweils nach Repository einschränken. Du kannst beispielsweise allen Repositorys Zugriff gewähren oder nur private Repositorys oder eine angegebene Liste von Repositorys zulassen.

Um Geheimnisse oder Variablen auf Organisationsebene zu erstellen, musst du über admin-Zugriff verfügen.

  1. Navigiere auf GitHub.com zur Hauptseite der Organisation. 1. Klicke unter deinem Organisationsnamen auf Einstellungen. Schaltfläche „Organisationseinstellungen“ 1. Wähle im Abschnitt Sicherheit der Randleiste Geheimnisse und Variablen, und klicke dann auf Aktionen. 1. Klicke auf die Registerkarte Variablen. Registerkarte „Organisationsvariablen“
  2. Klicke auf Neue Organisationsvariable.
  3. Gib im Feld Name einen Namen für deine Variable ein.
  4. Gib im Feld Wert den Wert für deine Variable ein.
  5. Wähle in der Dropdownliste Repositoryzugriff eine Zugriffsrichtlinie aus.
  6. Klicke auf Variable hinzufügen.

Grenzwerte für Konfigurationsvariablen

Du kannst bis zu 1.000 Organisationsvariablen, bis zu 100 Repositoryvariablen und bis zu 100 Umgebungsvariablen speichern.

Ein Workflow, der in einem Repository erstellt wurde, kann auf die folgende Anzahl von Variablen zugreifen:

  • Alle 100 Repositoryvariablen.
  • Wurde dem Repository der Zugriff auf mehr als 100 Organisationsvariablen zugewiesen, kann der Workflow nur die ersten 100 Organisationsvariablen (alphabetisch nach dem Namen der Variablen sortiert) verwenden.
  • Alle 100 Umgebungsvariablen.

Variablen haben eine Maximalgröße von 48 KB.

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 und des vars-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 }}

Verwenden des Kontexts vars für den Zugriff auf Konfigurationsvariablenwerte

Auf Konfigurationsvariablen kann im gesamten Workflow mithilfe des Kontexts vars zugegriffen werden. Weitere Informationen findest du unter Kontexte.

Wenn keine Konfigurationsvariable festgelegt wurde, ist der Rückgabewert eines Kontexts, der auf die Variable verweist, eine leere Zeichenfolge.

Die folgenden Beispiele zeigen das Verwenden von Konfigurationsvariablen mit dem Kontext vars in einem Workflow. Jede der folgenden Konfigurationsvariablen wurde auf Repository-, Organisations- oder Umgebungsebene definiert.

on:
  workflow_dispatch:
env:
  # Setting an environment variable with the value of a configuration variable
  env_var: ${{ vars.ENV_CONTEXT_VAR }}

jobs:
  display-variables:
    name: ${{ vars.JOB_NAME }}
    # You can use configuration variables with the `vars` context for dynamic jobs
    if: ${{ vars.USE_VARIABLES == 'true' }}
    runs-on: ${{ vars.RUNNER }}
    environment: ${{ vars.ENVIRONMENT_STAGE }}
    steps:
    - name: Use variables
      run: |
        echo "repository variable : ${{ vars.REPOSITORY_VAR }}"
        echo "organization variable : ${{ vars.ORGANIZATION_VAR }}"
        echo "overridden variable : ${{ vars.OVERRIDE_VAR }}"
        echo "variable from shell environment : $env_var"

    - name: ${{ vars.HELLO_WORLD_STEP }}
      if: ${{ vars.HELLO_WORLD_ENABLED == 'true' }}
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: ${{ vars.GREET_NAME }}

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.