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.
- Um eine Umgebungsvariable für die Verwendung in einem einzelnen Workflow zu definieren, kannst du den
env
-Schlüssel in der Workflowdatei verwenden. Weitere Informationen findest du unter Definieren von Umgebungsvariablen für einen einzelnen Workflow. - Um eine Konfigurationsvariable für mehrere Workflows zu definieren, kannst du sie auf Organisations-, Repository- oder Umgebungsebene definieren. Weitere Informationen findest du unter Definieren von Konfigurationsvariablen für mehrere Workflows.
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.
- Navigiere auf GitHub.com zur Hauptseite des Repositorys. 1. Klicke unter dem Repositorynamen auf Einstellungen.
1. Wähle im Abschnitt Sicherheit der Randleiste Geheimnisse und Variablen, und klicke dann auf Aktionen. 1. Klicke auf die Registerkarte Variablen. - Klicke auf Neue Repositoryvariable.
- Gib im Feld Name einen Namen für deine Variable ein.
- Gib im Feld Wert den Wert für deine Variable ein.
- 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.
- Navigiere auf GitHub.com zur Hauptseite des Repositorys. 1. Klicke unter dem Repositorynamen auf Einstellungen.
1. Klicke auf der linken Randleiste auf Umgebungen. - Klicke auf die Umgebung, der du eine Variable hinzufügen möchtest.
- Klicke unter Umgebungsvariablen auf Variable hinzufügen.
- Gib im Feld Name einen Namen für deine Variable ein.
- Gib im Feld Wert den Wert für deine Variable ein.
- 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.
-
Navigiere auf GitHub.com zur Hauptseite der Organisation. 1. Klicke unter deinem Organisationsnamen auf Einstellungen.
1. Wähle im Abschnitt Sicherheit der Randleiste Geheimnisse und Variablen, und klicke dann auf Aktionen. 1. Klicke auf die Registerkarte Variablen. -
Klicke auf Neue Organisationsvariable.
-
Gib im Feld Name einen Namen für deine Variable ein.
-
Gib im Feld Wert den Wert für deine Variable ein.
-
Wähle in der Dropdownliste Repositoryzugriff eine Zugriffsrichtlinie aus.
-
Klicke auf Variable hinzufügen.
Grenzwerte für Konfigurationsvariablen
Variablen sind auf eine Größe von je 48 KB begrenzt.
Du kannst bis zu 1.000 Organisationsvariablen, bis zu 500 Variablen pro Repository und bis zu 100 Variablen pro Umgebung speichern. Die kombinierte Gesamtgröße für Organisations- und Repositoryvariablen ist auf 256 KB pro Workflowausführung begrenzt.
Ein Workflow, der in einem Repository erstellt wurde, kann auf die folgende Anzahl von Variablen zugreifen:
- Bis zu 500 Repositoryvariablen, wenn die Gesamtgröße der Repositoryvariablen kleiner als 256 KB ist. Wenn die Gesamtgröße der Repositoryvariablen 256 KB überschreitet, sind nur die Repositoryvariablen verfügbar, die unter den Grenzwert fallen (alphabetisch sortiert nach Variablennamen).
- Bis zu 1.000 Organisationsvariablen, wenn die Gesamtgröße der Repository- und Organisationsvariablen kleiner als 256 KB ist. Wenn die Gesamtgröße der Organisations- und Repositoryvariablen 256 KB überschreitet, sind nur die Organisationsvariablen verfügbar, die unter diesen Grenzwert fallen (nach Berücksichtigung der Repositoryvariablen und alphabetisch sortiert nach Variablennamen).
- Bis zu 100 Variablen auf Umgebungsebene.
Hinweis: Variablen auf Umgebungsebene werden nicht auf das 256-KB-Limit für die Gesamtgröße angerechnet. Wenn du das kombinierte Größenlimit für Repository- und Organisationsvariablen überschreitest und dennoch zusätzliche Variablen benötigst, kannst du eine Umgebung verwenden und zusätzliche Variablen in der Umgebung definieren.
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 Kontexte.
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 DAY_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.
Kontext | Anwendungsfall | Beispiel |
---|---|---|
env | Verweisen auf benutzerdefinierte Variablen, die im Workflow definiert sind | ${{ env.MY_VARIABLE }} |
github | Verweisen 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.
Das folgende Beispiel zeigt die Verwendung 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.
Variable | BESCHREIBUNG |
---|---|
CI | Immer auf true festgelegt. |
GITHUB_ACTION | Name 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_PATH | Pfad 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_REPOSITORY | Bei 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_ACTIONS | Wenn 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_ACTOR | Name der Person oder App, die den Workflow initiiert hat. Beispiel: octocat . |
GITHUB_BASE_REF | Name 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_REF | Verweis 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_SHA | Der 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 zum Auslösen von Workflows. 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 Workflow commands for GitHub Actions (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.