Definieren von Umgebungsvariablen für einen einzelnen Workflow
Um eine benutzerdefinierte Umgebungsvariable für die Verwendung in einem einzelnen Workflow anzulegen, können Sie den env
-Schlüssel in der Workflowdatei definieren. Der Geltungsbereich einer mit dieser Methode festgelegten benutzerdefinierten Variable ist auf das Element beschränkt, in dem sie definiert wird. Sie können Variablen definieren, die für Folgendes gelten:
- Den gesamten Workflow, indem Sie
env
in der Workflowdatei auf der obersten Ebene verwenden - Der Inhalt eines Auftrags innerhalb eines Workflows unter Verwendung von
jobs.<job_id>.env
. - Einen bestimmten Schritt innerhalb eines Auftrags, indem Sie
jobs.<job_id>.steps[*].env
verwenden
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
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
Sie können auf env
-Variablenwerte mithilfe von Runnerumgebungsvariablen oder mithilfe von Kontexten zugreifen. Das Beispiel oben zeigt drei benutzerdefinierte Variablen, die als Umgebungsvariablen für Läufer in einem echo
Befehl 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. Die Interpolation dieser Variablen erfolgt auf dem Runner.
Die Befehle in den run
Schritten eines Workflows oder einer referenzierten Aktion werden von der Shell verarbeitet, die Sie auf dem Runner verwenden. Teile eines Workflows werden jedoch von GitHub Actions verarbeitet und nicht an den Runner gesendet. Sie können entweder Umgebungsvariablen des Runners oder Kontexte in run
Schritten verwenden, aber in den Teilen eines Workflows, die nicht an den Runner gesendet werden, müssen Sie Kontexte für den Zugriff auf Variablenwerte verwenden. Weitere Informationen findest du unter Verwenden von Kontexten für das Zugreifen auf Variablenwerte.
Da die Interpolation der Runnerumgebungsvariablen nach dem Senden eines Workflowauftrags an einen Runnercomputer durchgeführt wird, müssen Sie 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 müssen Sie in diesem Fall die Syntax $NAME
verwenden. Standardmäßig verwenden Windows-Runner PowerShell, sodass Sie die Syntax $env:NAME
verwenden würden. Weitere Informationen zu Shells findest du unter Workflowsyntax für GitHub Actions.
Definieren von Konfigurationsvariablen für mehrere Workflows
Sie können Konfigurationsvariablen für mehrere Workflows erstellen und diese entweder auf Organisations-, Repository- oder Umgebungsebene definieren.
Sie können 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 Sie Konfigurationsvariablen definieren, sind sie automatisch im vars
-Kontext verfügbar. Weitere Informationen findest du unter Verwenden des vars
-Kontexts für das Zugreifen auf Werte von Konfigurationsvariablen.
Erstellen von Konfigurationsvariablen für ein Repository
Um Geheimnisse oder Variablen auf GitHub für ein Repository eines persönlichen Kontos zu erstellen, müssen Sie Repositorybesitzer*in sein. Um Geheimnisse oder Variablen auf GitHub für ein Organisationsrepository zu erstellen, müssen Sie über admin
-Zugriff verfügen. Um Geheimnisse oder Variablen für ein Repository eines persönlichen Kontos oder einer Organisation über die REST-API zu erstellen, müssen Sie über Projektmitarbeiterzugriff verfügen.
-
Navigieren Sie auf GitHub zur Hauptseite des Repositorys.
-
Wähle unter dem Namen deines Repositorys die Option Einstellungen aus. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.
-
Wählen Sie im Abschnitt „Sicherheit“ in der Randleiste Geheimnisse und Variablen und klicken Sie dann auf Aktionen.
-
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 Repository eines persönlichen Kontos zu erstellen, müssen Sie Besitzer des Repositorys sein. Für das Erstellen von Geheimnissen oder Variablen für eine Umgebung in einem Organisationsrepository benötigen Sie admin
-Zugriff. Weitere Informationen zu Umgebungen findest du unter Verwalten von Umgebungen für die Bereitstellung.
-
Navigieren Sie auf GitHub zur Hauptseite des Repositorys.
-
Wähle unter dem Namen deines Repositorys die Option Einstellungen aus. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.
-
Klicke auf der linken Randleiste auf Umgebungen.
-
Klicken Sie auf die Umgebung, der Sie eine Variable hinzufügen möchten.
-
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
Hinweis
Auf Geheimnisse und Variablen auf Organisationsebene können private Repositorys für GitHub Free nicht zugreifen. Weitere Informationen zum Upgrade des GitHub-Abonnements sind unter Heraufstufen deines Kontoplans zu finden.
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.
Organisationsbesitzer*innen können Geheimnisse oder Variablen auf Organisationsebene erstellen.
-
Navigieren Sie auf GitHub zur Hauptseite der Organisation.
-
Klicke unter deinem Organisationsnamen auf die Option Einstellungen. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.
-
Wählen Sie im Abschnitt „Sicherheit“ in der Randleiste Geheimnisse und Variablen und klicken Sie dann auf Aktionen.
-
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.
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 Contexts reference. Es gibt noch viele weitere Kontexte, die Sie für verschiedene Zwecke in deinen Workflows verwenden können. Ausführliche Informationen zum Verwenden von bestimmten Kontexten innerhalb eines Workflows findest du unter Contexts reference.
Sie können die Werte der Umgebungsvariablen über den env
-Kontext und die Werte der Konfigurationsvariablen über den vars
-Kontext aufrufen.
Verwenden des env
-Kontexts für den Zugriff auf die Werte von Umgebungsvariablen
Neben Runnerumgebungsvariablen können Sie mit GitHub Actions mithilfe von Kontexten auch env
-Schlüsselwerte festlegen und lesen. Umgebungsvariablen und Kontexte sind für verschiedene Stellen im Workflow vorgesehen.
Die run
Schritte in einem Workflow oder in einer referenzierten Aktion werden von einem Runner verarbeitet. Daher können Sie hier Umgebungsvariablen für den Runner verwenden, wobei Sie die entsprechende Syntax für die auf dem Runner verwendete Shell verwenden - zum Beispiel $NAME
für die Bash-Shell auf einem Linux-Runner oder $env:NAME
für PowerShell auf einem Windows-Runner. In den meisten Fällen können Sie auch Kontexte mit der Syntax ${{ CONTEXT.PROPERTY }}
verwenden, um auf denselben Wert zuzugreifen. Der Unterschied besteht darin, dass der Kontext interpoliert und durch eine Zeichenfolge ersetzt wird, bevor der Auftrag an einen Runner gesendet wird.
Sie können jedoch keine Runner-Umgebungsvariablen in Teilen eines Workflows verwenden, die von GitHub Actions verarbeitet und nicht an den Runner gesendet werden. Stattdessen kann man 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. Sie müssen daher einen Kontext in einer if
-bedingten Anweisung verwenden, um auf den Wert einer Variablen zuzugreifen.
name: Conditional env variable 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" if: ${{ env.DAY_OF_WEEK == 'Monday' }} run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!" env: First_Name: Mona
name: Conditional env variable
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"
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. Der env
-Kontext ist für die Variablen, auf die innerhalb des run
-Befehls verwiesen wird nicht erforderlich. Sie werden als Runner-Umgebungsvariablen referenziert und interpoliert, nachdem der Auftrag vom Runner empfangen wurde. Wir könnten diese Variablen jedoch interpolieren, bevor wir den Auftrag an den Runner senden, indem wir Kontexte verwenden. Das Ergebnis wäre das gleiche.
run: echo "${{ env.Greeting }} ${{ env.First_Name }}. Today is ${{ env.DAY_OF_WEEK }}!"
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 Sie diese Zeichen verwenden, müssen sie jedoch die gesamte Vergleichsanweisung umschließen, wie oben zu sehen.
Warnung
Bei der Erstellung von Workflows und Aktionen sollten Sie immer bedenken, ob Ihr Code nicht vertrauenswürdige Eingaben von möglichen Eindringlingen ausführen könnte. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen finden Sie unter Sicherheitshärtung für GitHub Actions.
Verwenden des Kontexts vars
für den Zugriff auf Konfigurationsvariablenwerte
Auf Konfigurationsvariablen kann im gesamten Workflow mithilfe des Kontexts vars
zugegriffen werden. Weitere Informationen finden Sie unter Contexts reference.
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 : $REPOSITORY_VAR" echo "organization variable : $ORGANIZATION_VAR" echo "overridden variable : $OVERRIDE_VAR" echo "variable from shell environment : $env_var" env: REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }} ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }} OVERRIDE_VAR: ${{ vars.OVERRIDE_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 }}
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 : $REPOSITORY_VAR"
echo "organization variable : $ORGANIZATION_VAR"
echo "overridden variable : $OVERRIDE_VAR"
echo "variable from shell environment : $env_var"
env:
REPOSITORY_VAR: ${{ vars.REPOSITORY_VAR }}
ORGANIZATION_VAR: ${{ vars.ORGANIZATION_VAR }}
OVERRIDE_VAR: ${{ vars.OVERRIDE_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 }}
Erkennen des Betriebssystems
Mithilfe der Standardumgebungsvariable RUNNER_OS
und der entsprechenden Kontexteigenschaft ${{ runner.os }}
können Sie eine einzelne Workflowdatei erstellen, die für verschiedene Betriebssysteme verwendet werden kann. Beispielsweise könnte der folgende Workflow erfolgreich ausgeführt werden, wenn Sie das Betriebssystem von macos-latest
in windows-latest
ändern, ohne dass die Syntax der Umgebungsvariablen angepasst werden muss, die je nachdem, welche Shell auf dem Runner verwendet wird, unterschiedlich ist.
on: workflow_dispatch 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."
on: workflow_dispatch
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, können Sie diesen in darauffolgenden Schritten desselben Auftrags verwenden, indem Sie den Wert einer bereits vorhandenen oder neuen Umgebungsvariable zuweisen und diese dann in die GITHUB_ENV
-Umgebungsdatei schreibsen. Die Umgebungsdatei kann direkt von einer Aktion oder über einen Shellbefehl in der Workflowdatei mit dem Schlüsselwort run
verwendet werden. Weitere Informationen finden Sie unter Workflow commands for GitHub Actions (Workflowbefehle für GitHub Actions).
Wenn Sie einen Wert von einem Schritt in einem Auftrag in einem bestimmten Workflow an einen Schritt in einem anderen Auftrag in diesem Workflow übergeben möchten, können sie den Wert als Auftragsausgabe definieren. Dann können Sie in einem Schritt in einem anderen Auftrag auf diese Auftragsausgabe verweisen. Weitere Informationen finden Sie unter Workflowsyntax für GitHub Actions.