Wie Sie die Umgebungsvariablen von GitHub Actions verwenden

Um die Effizienz der Freigabe von funktionierendem Code in eine Produktionsumgebung zu verbessern, ist die Implementierung einer kontinuierlichen Integrations- und Auslieferungspipeline (CI/CD) eine gute Praxis. Diese Pipelines automatisieren den Prozess der Überprüfung, ob eine Codeänderung für die Freigabe bereit ist, und stellen Tools zur Verfügung, um die Freigabe in eine Produktionsumgebung zu automatisieren.

Ein beliebter Weg, dies zu tun, ist die Verwendung Ihres vorhandenen Versionskontrollsystems. GitHub ist eines der beliebtesten Versionskontrollsysteme und stellt GitHub Actions zur Verfügung, mit denen Entwickler/innen Code automatisch erstellen, testen und bereitstellen können, was zum Aufbau sicherer CI/CD-Pipelines beiträgt.

Es ist üblich, dass Jobs innerhalb von GitHub Actions Zugriff auf Umgebungsvariablen benötigen. Diese Variablen können im Voraus definiert werden und nur von Pipelines genutzt werden, die in dieser bestimmten Umgebung ausgeführt werden. Auf diese Weise können Entwickler/innen das Verhalten der CI/CD-Pipeline auf der Grundlage von Umgebungsvariablen ändern, z. B. indem sie vor der Bereitstellung in die Produktion zur Erstellung einer optimierten Produktionsversion der Anwendung wechseln.

In diesem praktischen Artikel erfahren Sie, welche Umgebungsvariablen in GitHub Actions zur Verfügung stehen und wann wir sie verwenden sollten.

Voraussetzungen

Um diesem Tutorial zu folgen, benötigen Sie Folgendes:

• Zugriff auf einen Rechner mit einem Code-Editor (dieses Tutorial verwendet Visual Studio Code) und ein GitHub-Konto.

• den Beispielcode. Der Beispielcode enthält eine einfache Java-Anwendung, mit der wir demonstrieren, wie Umgebungsvariablen funktionieren.

Wussten Sie, dass wir ein Visual Studio Code Snyk Plug-in haben, damit Sie Ihr Projekt während der Entwicklung scannen können? Lesen Sie die Dokumentation für weitere Informationen.

Was Sie mit den GitHub Actions-Umgebungsvariablen tun können

Sobald Sie den Beispielcode heruntergeladen haben, erstellen Sie ein neues Repository in GitHub und fügen Sie den Beispielcode zu diesem Repository hinzu.

Der Beispielcode enthält bereits eine GitHub Actions Workflow-Datei. Das Code-Snippet unten zeigt den Inhalt der Datei .github/workflows/pipeline.yml:

1name: Java CI with Maven
2
3on:
4  push:
5    branches: [ "main" ]
6  pull_request:
7    branches: [ "main" ]
8
9jobs:
10  build:
11
12    runs-on: ubuntu-latest
13
14    steps:
15    - uses: actions/checkout@v3
16    - name: Set up JDK 21
17      uses: actions/setup-java@v3
18      with:
19        java-version: '21'
20        distribution: 'temurin'
21        cache: maven
22    - name: Build with Maven
23      run: mvn -B package --file pom.xml

Diese Datei definiert einen einfachen Arbeitsablauf zur Erstellung unserer Java-Anwendung mit Maven.

Wir können Umgebungsvariablen in der Workflow-YAML-Konfigurationsdatei auf drei Ebenen definieren – Workflow, Job und Step. Diese Ebenen bestimmen den Umfang der Umgebungsvariablen. Auf der Workflow-Ebene werden Umgebungsvariablen verwendet, die für den gesamten Workflow gelten. Auf der Job-Ebene werden Umgebungsvariablen verwendet, die für bestimmte Jobs gelten. Step-Umgebungsvariablen gelten für bestimmte Schritte.

Lassen Sie uns jede dieser Variablen im Detail betrachten.

Workflow-Umgebungsvariablen

Um eine Umgebungsvariable auf Workflow-Ebene einzurichten, müssen wir sie auf der obersten Ebene der YAML-Datei definieren. Fügen Sie den folgenden Code unterhalb der Variable NAME am Anfang der Datei ein:

1env:
2  NAME: 'Snyk Demo'

Dieser Code definiert eine Umgebungsvariable mit dem Namen NAME, auf die wir nun überall in unserem Workflow zugreifen können. Um auf diese Variable zuzugreifen, müssen wir eine spezielle Syntax verwenden, die der Syntax für den Zugriff auf UNIX-Umgebungsvariablen ähnelt. Um unsere Variable NAME zu verwenden, müssen wir ihr ein Dollarzeichen voranstellen und so die Variable in $NAME ändern.

Fügen wir unserem Workflow in Zeile 23 einen neuen Schritt hinzu, der diese Variable ausgibt:

1- name: Print name
2  run: echo "Hello $NAME"

Commit und Übergabe dieser Änderung an das Repository.

Öffnen Sie dann GitHub in einem Browser und navigieren Sie zum Tab Actions innerhalb des Repositorys. Wählen Sie unter Jobs den neuesten Workflow aus und öffnen Sie die Ausgabe unseres Build-Jobs. Klicken Sie auf Name ausgeben. Nach dem Erweitern sehen Sie, dass die Umgebungsvariable erfolgreich ausgegeben wurde, wie in der Abbildung unten zu sehen ist.

Umgebungsvariablen auf Workflow-Ebene sind nützlich, um Variablen zu deklarieren, die für jeden Job und Step gelten. Damit können wir beispielsweise festlegen, in welcher Art von Umgebung der Workflow ausgeführt wird, z. B. Entwicklung, Test oder Produktion. Dies kann für Node-Anwendungen, die mit npm erstellt wurden, nützlich sein, da sie die Variable NODE_ENV verwenden können. Durch die Verwendung dieser Variable kann sich jeder Job entsprechend der jeweiligen Umgebung verhalten. Mehr über die sichere Veröffentlichung Ihrer npm-Pakete erfahren Sie in diesem Artikel im Snyk Blog.

Job-Umgebungsvariablen

Sehen wir uns nun die Einrichtung von Job- und Step-Umgebungsvariablen an. Diese können auf die gleiche Weise eingerichtet werden wie unsere Workflow-Umgebungsvariablen, aber wir definieren sie innerhalb des entsprechenden Abschnitts.

Für unsere Job-Variable wollen wir die Java-Version wie folgt definieren:

1jobs:
2  build:
3    env:
4        JAVA_VERSION: '21'

Innerhalb unserer Steps können wir diese Variable nun wie zuvor verwenden.

1steps:
2- uses: actions/checkout@v3
3- name: Set up JDK ${{env.JAVA_VERSION}}
4  uses: actions/setup-java@v3
5  with:
6    java-version: ${{env.JAVA_VERSION}}
7    distribution: 'temurin'
8    cache: maven

Sie werden jedoch feststellen, dass die Syntax bei der Verwendung unserer Umgebungsvariablen JAVA_VERSION etwas anders ist. Dies ist ein Beispiel für die Verwendung von Kontexten für den Zugriff auf eine Umgebungsvariable. Kontexte ermöglichen es GitHub Actions, unsere Umgebungsvariablen auf einer beliebigen virtuellen Maschine zu verwenden, da diese Aufgaben nicht immer auf derselben virtuellen Maschine ausgeführt werden, auf der wir unsere Umgebung deklarieren.

Sie können Job-Umgebungsvariablen verwenden, um eine Umgebung auf Workflow-Ebene außer Kraft zu setzen, wenn ein bestimmter Job einen anderen Wert für eine bereits deklarierte Workflow-Variable benötigt, oder um den Geltungsbereich der Variable auf einen bestimmten Job zu beschränken.

Wie im obigen Beispiel gezeigt, können wir Job-Umgebungsvariablen verwenden, um die Java-Version festzulegen, sodass wir die Variable in jedem Schritt verwenden können. Wenn wir in Zukunft eine andere Java-Version verwenden möchten, müssen wir sie nur an einer Stelle ändern, und alle Steps innerhalb des Jobs verwenden automatisch die neue Version.

Da Sie nun bereits an einer GitHub Action arbeiten, können Sie Snyk ganz einfach in Ihre GitHub Actions integrieren und Ihr Projekt sofort scannen. Wir haben vorgefertigte Snyk GitHub Actions verfügbar für Sie. Melden Sie sich also für ein Snyk-Konto an, falls Sie das noch nicht getan haben, und integrieren Sie das Scannen noch heute.

Step-Umgebungsvariablen

Wir können auch Variablen innerhalb eines Schrittes definieren. Im Folgenden finden Sie ein Beispiel für eine Step-Umgebungsvariable. Ändern Sie den Schritt Name ausgeben in der Datei pipeline.yml so ab, dass er dem unten stehenden Code-Snippet entspricht:

1- name: Print name
2  run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
3  env:
4    BUILD: 'We are currently running the Build job'

Step-Umgebungsvariablen beschränken den Geltungsbereich auf einen einzigen Schritt. Dies ist nützlich für Aufgaben wie die Definition von Dateipfaden für Eingabe- oder Ausgabedateien, die für einen Schritt spezifisch sind. Im obigen Beispielcode haben wir die Step-Variable verwendet, um einen Text zum Ausgeben festzulegen.

Nachfolgend sehen Sie ein Beispiel für die vollständige YAML-Datei des GitHub-Workflows, in der die neuen Job- und Step-Umgebungsvariablen hinzugefügt wurden:

1name: Java CI with Maven
2
3env:
4  NAME: 'Snyk Demo'
5
6on:
7  push:
8    branches: [ "main" ]
9  pull_request:
10    branches: [ "main" ]
11
12jobs:
13  build:
14    env:
15        JAVA_VERSION: '21'
16
17    runs-on: ubuntu-latest
18
19    steps:
20    - uses: actions/checkout@v3
21    - name: Set up JDK ${{env.JAVA_VERSION}}
22      uses: actions/setup-java@v3
23      with:
24        java-version: ${{env.JAVA_VERSION}}
25        distribution: 'temurin'
26        cache: maven
27    - name: Build with Maven
28      run: mvn -B package --file pom.xml
29    - name: Print name
30      run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION"
31      env:
32        BUILD: 'We are currently running the Build job'

Checken Sie diesen neuen Workflow in GitHub ein und werfen Sie einen Blick auf die Ausgabe, die wie das folgende Bild aussehen sollte.

Wir haben unsere Umgebungsvariable mithilfe von Kontexten eingerichtet und unser Print-Schritt funktioniert wie erwartet.

Wenn wir versucht hätten, unsere Umgebungsvariable ohne Kontexte zu verwenden, hätten wir die folgende Fehlermeldung erhalten:

Das liegt daran, dass die Aktion setup-java keinen Zugriff auf dieselbe Umgebung hat. Daher ist die Verwendung von Kontexten erforderlich, um die Variable verfügbar zu machen.

Verwendung von Standardvariablen und GitHub Secrets

Zusätzlich zur Definition unserer Umgebungsvariablen bietet GitHub einige Standardvariablen, auf die Sie innerhalb eines Workflows zugreifen können. Diese Variablen geben uns Zugriff auf Details wie das GitHub-Repository, die GitHub Action und den Runner für den Workflow. Sie können sie auf die gleiche Weise wie benutzerdefinierte Umgebungsvariablen verwenden. Bei der Verwendung von GitHub Actions müssen Sie gegebenenfalls über Kontexte auf sie zugreifen.

Der letzte Typ von Umgebungsvariablen sind die GitHub Secrets. Sie können sie für Variablen verwenden, die sensible Daten enthalten, da GitHub sie verschlüsselt und innerhalb Ihres Workflows verfügbar macht.

Sie können verschlüsselte Umgebungsvariablen in GitHub erstellen, indem Sie zum Bereich Einstellungen für das Repository gehen und Secrets und Variablen, und dann Actions aus dem Menü auf der linken Seite auswählen. Klicken Sie dann auf Neues Repository-Secret und geben Sie einen Namen und einen Wert für Ihr Secret ein. Erstellen Sie ein Secret mit dem Namen API_KEY und geben Sie ihm einen zufälligen Wert, wie unten gezeigt.

Um das Secret innerhalb des Workflows zu verwenden, verwenden wir die gleiche Syntax wie bei der Verwendung von Kontexten, um GitHub Actions Umgebungsvariablen zu übergeben. Anstatt der Variable jedoch env. voranzustellen, verwenden wir stattdessen secrets..

1${{secrets.API_KEY}}

Fügen Sie ${{secrets.API_KEY}} zu der Print-Anweisung hinzu, die wir bereits in der Workflow-YAML-Datei erstellt haben. Sie sollte mit dem Code-Snippet unten übereinstimmen:

1- name: Print name
2  run: echo "Hello $NAME. $BUILD. Using Java Version $JAVA_VERSION. My API_KEY is ${{secrets.API_KEY}}"
3  env:
4    BUILD: 'We are currently running the Build job'

Commiten Sie die Änderungen und stellen Sie sie in das Repository ein. Rufen Sie dann die Seite Actions auf GitHub auf, um die Ausgabe des letzten Workflow-Runs zu sehen.

Wie wir sehen, maskiert GitHub automatisch den Wert unseres verschlüsselten Secrets, damit wir es nicht versehentlich preisgeben.

Mit GitHub Secrets können Sie sensible Daten wie Kennwörter oder API-Autorisierungsschlüssel speichern. Durch die Verwendung von Secrets müssen wir diese Werte in unserem Workflow nicht hartkodieren und riskieren, dass sie nach außen gelangen. Stattdessen verschlüsselt GitHub sie für uns, leitet sie sicher an alle Actions in unserem Workflow weiter und stellt sicher, dass sie nicht im Klartext in den Protokollen erscheinen.

Fazit

In diesem Artikel wurden die Umgebungsvariablen von GitHub Actions erläutert. Wir haben die drei Bereiche besprochen, die für Umgebungsvariablen zur Verfügung stehen (Workflow, Job und Step), und wie man Variablen in jedem dieser Bereiche definiert. Dann haben wir uns die Verwendung von Kontexten zur Übergabe von Umgebungsvariablen an GitHub Actions und die Verwendung von Secrets zur Verschlüsselung sensibler Variablen angesehen.

GitHub Actions-Umgebungsvariablen ermöglichen es Entwicklerinnen/Entwicklern, dynamische Workflows zu erstellen. Wir können diese Variablen verwenden, um das Verhalten des Workflows entweder auf der Grundlage einer benutzerdefinierten Variable oder einer Standard-GitHub-Variable zu ändern. Wir sollten Variablen immer dann verwenden, wenn wir dynamisch ändern möchten, wie der Workflow oder ein bestimmter Job oder Step funktioniert und auch wann er ausgeführt werden soll.

In dem Artikel wurde auch die Verwendung von GitHub Secrets als Umgebungsvariablen zum Schutz vertraulicher Informationen besprochen. Es ist wichtig, dass Sie daran denken, GitHub Secrets für sensible Variablen wie Passwörter und API-Schlüssel zu verwenden, da GitHub sie verschlüsselt und in einen Workflow einfügt, ohne dass die Gefahr besteht, dass sie preisgegeben werden.

Und denken Sie daran: Sicherheit ist wichtig! Erfahren Sie, wie Snyk Ihren GitHub-Workflows eine zusätzliche Sicherheitsebene verleihen kann, und erfahren Sie mehr über die Integration von Snyk in Ihre CI/CD-Pipeline für umfassende Sicherheit für Code, Container, Open Source und IaC.