GitHub-Actions-Umgebungsvariablen verwenden

Play Video: How to Use GitHub Actions Environment Variables and Secrets

Um die Effizienz bei der Bereitstellung funktionsfähigen Codes in einer Produktionsumgebung zu verbessern, empfiehlt sich die Implementierung einer Continuous-Integration- und Continuous-Delivery-Pipeline (CI/CD). Diese Pipelines automatisieren die Prüfung, ob eine Codeänderung bereit für die Veröffentlichung ist, und bieten Tools, mit denen sich die Bereitstellung in einer Produktionsumgebung automatisieren lässt.

Eine beliebte Möglichkeit dafür ist die Verwendung Ihres vorhandenen Versionskontrollsystems. GitHub zählt zu den beliebtesten Versionskontrollsystemen und bietet GitHub Actions. Damit können Entwickler Code automatisch erstellen, testen und bereitstellen und so sichere CI/CD-Pipelines erstellen.

Bei Jobs in GitHub Actions ist es üblich, dass sie Zugriff auf Umgebungsvariablen benötigen. Diese Variablen können vorab definiert und nur von Pipelines abgerufen werden, die in der jeweiligen Umgebung ausgeführt werden. So können Entwickler das Verhalten der CI/CD-Pipeline anhand von Umgebungsvariablen ändern, beispielsweise indem sie vor der Bereitstellung in der Produktion eine optimierte Produktionsversion der Anwendung erstellen lassen.

Dieser praxisorientierte Artikel behandelt die in GitHub Actions verfügbaren Umgebungsvariablen und erklärt, wann Sie sie verwenden sollten.

Voraussetzungen

Für dieses Tutorial benötigen Sie Folgendes:

• Zugriff auf einen Rechner mit einem Code-Editor (in diesem Tutorial verwenden wir Visual Studio Code) und ein GitHub-Konto.

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

Wussten Sie, dass es ein Visual Studio Code-Snyk-Plugin gibt, mit dem Sie Ihr Projekt bereits während der Entwicklung scannen können? Weitere Informationen finden Sie in der Dokumentation.

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

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

Der Beispielcode enthält bereits eine Beispiel-Workflow-Datei für GitHub Actions. Das folgende Code-Snippet 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 Workflow, um unsere Java-Anwendung mit Maven zu erstellen.

Umgebungsvariablen können in der YAML-Konfigurationsdatei des Workflows auf drei Ebenen definiert werden: Workflow, Job und Schritt. Diese Ebenen bestimmen den Gültigkeitsbereich der Umgebungsvariablen. Variablen auf Workflow-Ebene gelten für den gesamten Workflow. Variablen auf Job-Ebene gelten für bestimmte Jobs. Variablen auf Schritt-Ebene gelten für bestimmte Schritte.

Sehen wir uns die einzelnen Variablen genauer an.

Umgebungsvariablen auf Workflow-Ebene

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

1env:
2  NAME: 'Snyk Demo'

Dieser Code definiert eine Umgebungsvariable namens NAME, auf die wir nun überall in unserem Workflow zugreifen können. Dafür müssen wir eine bestimmte Syntax verwenden, die der beim Zugriff auf UNIX-Umgebungsvariablen ähnelt. Um unsere Variable NAME zu verwenden, stellen wir ihr ein Dollarzeichen voran und ändern sie so in $NAME.

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

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

Übernehmen Sie diese Änderung und übertragen Sie sie in das Repository.

Öffnen Sie anschließend GitHub in einem Browser und wechseln Sie im Repository zum Tab Actions. Wählen Sie unter Jobs den neuesten Workflow aus und öffnen Sie die Ausgabe unseres Build-Jobs. Klicken Sie auf Print name. Nach dem Aufklappen sehen Sie, dass die Umgebungsvariable erfolgreich ausgegeben wurde, wie im Bild unten zu sehen.

Umgebungsvariablen auf Workflow-Ebene eignen sich, um Variablen festzulegen, die für alle Jobs und Schritte gelten. So können wir beispielsweise angeben, in welcher Umgebung der Workflow ausgeführt wird, etwa in der Entwicklungs-, Test- oder Produktionsumgebung. Das ist nützlich für Node-Anwendungen, die mit npm erstellt wurden, da sie die Variable NODE_ENV verwenden können. Mithilfe dieser Variablen kann jeder Job passend zur jeweiligen Umgebung ausgeführt werden. Weitere Informationen zum sicheren Veröffentlichen Ihrer npm-Pakete finden Sie in diesem Artikel im Snyk-Blog.

Umgebungsvariablen auf Job-Ebene

Sehen wir uns nun an, wie Umgebungsvariablen auf Job- und Schritt-Ebene eingerichtet werden. Sie lassen sich genauso einrichten wie unsere Workflow-Umgebungsvariablen, werden jedoch im jeweiligen Abschnitt definiert.

Für unsere Job-Variable möchten wir die Java-Version wie folgt definieren:

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

In unseren Schritten 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

Bei der Verwendung unserer Umgebungsvariablen JAVA_VERSION fällt Ihnen möglicherweise eine leicht abweichende Syntax auf. Hier verwenden wir Kontexte, um auf eine Umgebungsvariable zuzugreifen. Kontexte ermöglichen GitHub Actions den Zugriff auf unsere Umgebungsvariablen auf jeder virtuellen Maschine, da diese Aufgaben nicht immer auf derselben virtuellen Maschine ausgeführt werden, auf der wir unsere Umgebung definieren.

Mit Umgebungsvariablen auf Job-Ebene können Sie eine Umgebung auf Workflow-Ebene überschreiben, wenn ein bestimmter Job einen anderen Wert für eine bereits definierte Workflow-Variable benötigt. Alternativ können Sie damit den Gültigkeitsbereich der Variable auf einen einzelnen Job beschränken.

Wie im obigen Beispiel gezeigt, können wir mit Umgebungsvariablen auf Job-Ebene die Java-Version festlegen und die Variable in jedem Schritt verwenden. Wenn wir künftig eine andere Java-Version verwenden möchten, müssen wir sie nur an einer Stelle ändern. Alle Schritte im Job verwenden dann automatisch die neue Version.

Da Sie bereits mit einer GitHub Action arbeiten, können Sie Snyk ganz einfach in Ihre GitHub Actions integrieren und Ihr Projekt sofort scannen. Zu Ihrer Unterstützung stehen vorgefertigte Snyk-GitHub-Actions zur Verfügung. Erstellen Sie also ein Snyk-Konto, falls Sie noch keines haben, und integrieren Sie noch heute das Scannen.

Umgebungsvariablen auf Schritt-Ebene

Sie können Variablen auch innerhalb eines Schritts definieren. Das folgende Beispiel zeigt eine Umgebungsvariable auf Schritt-Ebene. Ändern Sie den Schritt Print name in der Datei pipeline.yml, sodass er dem folgenden 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'

Umgebungsvariablen auf Schritt-Ebene beschränken den Gültigkeitsbereich auf einen einzelnen Schritt. Das ist nützlich, um beispielsweise Dateipfade für Eingabe- oder Ausgabedateien festzulegen, die für einen bestimmten Schritt gelten. Im obigen Beispielcode haben wir die Schrittvariable verwendet, um einen Text zur Ausgabe festzulegen.

Im Folgenden sehen Sie ein Beispiel für die vollständige GitHub-Workflow-YAML-Datei mit den neuen Umgebungsvariablen auf Job- und Schritt-Ebene:

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'

Übernehmen Sie diesen neuen Workflow in GitHub und sehen Sie sich die Ausgabe an. Sie sollte wie im folgenden Bild aussehen.

Wir haben unsere Umgebungsvariable mithilfe von Kontexten eingerichtet, und unser Ausgabeschritt funktioniert wie erwartet.

Wenn wir versucht hätten, unsere Umgebungsvariable ohne Kontexte zu verwenden, wäre der folgende Fehler aufgetreten:

Der Grund dafür ist, dass die setup-java action nicht auf dieselbe Umgebung zugreifen kann. Daher sind Kontexte erforderlich, um die Variable verfügbar zu machen.

Standardvariablen und GitHub-Secrets verwenden

Zusätzlich zu den selbst definierten Umgebungsvariablen stellt GitHub einige Standardvariablen bereit, auf die Sie in einem Workflow zugreifen können. Diese Variablen ermöglichen den Zugriff auf Informationen wie das GitHub-Repository, die GitHub Action und den Runner des Workflows. Sie lassen sich genauso verwenden wie benutzerdefinierte Umgebungsvariablen. Wo zutreffend, müssen Sie in GitHub Actions über Kontexte auf sie zugreifen.

Die letzte Art von Umgebungsvariablen sind GitHub-Secrets. Sie eignen sich für Variablen mit vertraulichen Daten, da GitHub sie verschlüsselt und im Workflow verfügbar macht.

Sie können verschlüsselte Umgebungsvariablen in GitHub erstellen, indem Sie die Settings des Repositorys öffnen und links im Menü Secrets and variables und anschließend Actions auswählen. Klicken Sie dann auf New repository secret und geben Sie einen Namen sowie einen Wert für Ihr Secret ein. Erstellen Sie ein Secret namens API_KEY und weisen Sie ihm einen beliebigen Wert zu, wie unten gezeigt.

Um das Secret im Workflow zu verwenden, nutzen wir dieselbe Syntax wie beim Bereitstellen von Umgebungsvariablen für GitHub Actions über Kontexte. Anstelle des Präfixes env. verwenden wir jedoch secrets..

1${{secrets.API_KEY}}

Fügen Sie ${{secrets.API_KEY}} in die bereits erstellte Print-Anweisung der Workflow-YAML-Datei ein. Sie sollte dem folgenden Code-Snippet entsprechen:

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'

Übernehmen Sie die Änderungen und übertragen Sie sie in das Repository. Rufen Sie dann die Seite Actions in GitHub auf, um die Ausgabe des neuesten Workflow-Laufs anzusehen.

Wie Sie sehen, maskiert GitHub den Wert unseres verschlüsselten Secrets automatisch, damit wir ihn nicht versehentlich offenlegen.

GitHub-Secrets helfen dabei, vertrauliche Daten wie Passwörter oder API-Autorisierungsschlüssel zu speichern. Verwenden Sie für vertrauliche Werte keine hartcodierten Angaben im Workflow, durch die sie externen Personen offengelegt werden könnten. GitHub-Secrets bieten eine sichere Alternative: GitHub verschlüsselt die Werte, übergibt sie sicher an die Actions im Workflow und verhindert, dass sie in Protokollen im Klartext erscheinen.

Fazit

In diesem Artikel haben wir GitHub-Actions-Umgebungsvariablen erläutert. Wir haben die drei verfügbaren Gültigkeitsbereiche (Workflow, Job und Schritt) sowie die Definition von Variablen für jeden dieser Bereiche behandelt. Anschließend haben wir uns angesehen, wie sich Umgebungsvariablen mithilfe von Kontexten an GitHub Actions übergeben und vertrauliche Variablen mit Secrets verschlüsseln lassen.

GitHub-Actions-Umgebungsvariablen ermöglichen Entwicklern, dynamische Workflows zu erstellen. Mithilfe dieser Variablen können wir das Verhalten des Workflows anhand einer benutzerdefinierten oder einer standardmäßigen GitHub-Variable ändern. Variablen sollten Sie immer dann verwenden, wenn Sie dynamisch ändern möchten, wie der Workflow oder ein bestimmter Job oder Schritt funktioniert und wann er ausgeführt wird.

Der Artikel hat außerdem gezeigt, wie sich GitHub-Secrets als Umgebungsvariablen verwenden lassen, um vertrauliche Informationen zu schützen. Denken Sie daran, für sensible Werte wie Passwörter und API-Schlüssel GitHub-Secrets zu verwenden. GitHub verschlüsselt diese und fügt sie in den Workflow ein, ohne sie offenzulegen.

Und denken Sie daran: Sicherheit ist wichtig! Erfahren Sie, wie Snyk Ihre GitHub-Workflows zusätzlich absichern kann, und lesen Sie mehr darüber, wie Sie Snyk in Ihre CI/CD-Pipeline integrieren, um Code, Container, Open Source und IaC umfassend abzusichern.