Anpassen Ihres Workflows mit Umgebungsvariablen und Artefaktdaten

12 Minuten

Hier erfahren Sie, wie Sie Standardumgebungsvariablen, benutzerdefinierte Umgebungsvariablen und Skripts, Cacheabhängigkeiten und Artefaktdaten zwischen Aufträgen übergeben. Außerdem wird erläutert, wie Sie über die GitHub-Website und über REST-API-Endpunkte auf die Workflowprotokolle zugreifen.

Standardumgebungsvariablen und -kontexte

Innerhalb des GitHub Actions-Workflows sind mehrere Standardumgebungsvariablen verfügbar, die Sie verwenden können, jedoch nur innerhalb des Runners, der einen Auftrag ausgeführt. Bei diesen Standardvariablen wird die Groß-/Kleinschreibung beachtet. Sie beziehen sich auf Konfigurationswerte für das System und den aktuellen Benutzer. Es wird empfohlen, für Verweise auf das Dateisystem diese Standardumgebungsvariablen anstelle von hartcodierten Dateipfaden zu verwenden. Geben Sie $ gefolgt vom Namen der Umgebungsvariablen an, um eine Standardumgebungsvariable zu verwenden.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Zusätzlich zu den Standardumgebungsvariablen können Sie definierte Variablen als Kontexte verwenden. Kontexte und Standardvariablen sind ähnlich, da sie beide den Zugriff auf Umgebungsinformationen ermöglichen. Es bestehen jedoch auch wichtige Unterschiede. Während Standardumgebungsvariablen nur innerhalb des Runners verwendet werden können, können Kontextvariablen jederzeit innerhalb des Workflows verwendet werden. Mit Kontextvariablen können Sie beispielsweise eine if-Anweisung ausführen, um einen Ausdruck vor der Ausführung des Runners auszuwerten.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

In diesem Beispiel wird der github.ref-Kontext verwendet, um den Branch zu überprüfen, der den Workflow ausgelöst hat. Wenn der Branch main ist, wird der Runner ausgeführt und gibt "Deploying to production server on branch $GITHUB_REF" aus. Die Standardumgebungsvariable $GITHUB_REF wird im Runner verwendet, um auf den Branch zu verweisen. Beachten Sie, dass Standardumgebungsvariablen alle groß geschrieben sind, während Kontextvariablen alle klein geschrieben sind.

Benutzerdefinierte Umgebungsvariablen

So wie Sie Standardumgebungsvariablen verwenden, können Sie benutzerdefinierte Umgebungsvariablen in Ihrer Workflowdatei einsetzen. Für die Erstellung einer benutzerdefinierten Variablen müssen Sie sie mithilfe des env-Kontexts in Ihrer Workflowdatei definieren. Wenn Sie den Wert einer Umgebungsvariablen innerhalb eines Runners verwenden möchten, können Sie die normale Methode des Runnerbetriebssystems zum Lesen von Umgebungsvariablen verwenden.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Skripts in Ihrem Workflow

In den Beispielen für Workflowausschnitte oben wird das Schlüsselwort run verwendet, um einfach eine Textzeichenfolge auszugeben. Da das Schlüsselwort run den Auftrag anweist, einen Befehl auf dem Runner auszuführen, werden Aktionen oder Skripts mit dem Schlüsselwort run ausgeführt.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

In diesem Beispiel verwenden Sie npm, um das batsSoftwaretestpaket mithilfe des Schlüsselworts run zu installieren. Sie können ein Skript auch als Aktion ausführen. Sie können das Skript in Ihrem Repository speichern. Dazu wird häufig ein .github/scripts/-Verzeichnis verwendet. Anschließend können Sie den Pfad und den Shelltyp mithilfe des Schlüsselworts run bereitstellen.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

Zwischenspeichern von Abhängigkeiten mit der Cacheaktion

Beim Erstellen eines Workflows müssen Sie häufig dieselben Ausgaben wiederverwenden oder Abhängigkeiten aus einer Ausführung in eine andere herunterladen. Anstatt diese Abhängigkeiten immer wieder herunterzuladen, können Sie sie zwischenspeichern, damit Ihr Workflow schneller und effizienter ausgeführt wird. Dies kann die Zeit, die zum Ausführen bestimmter Schritte in einem Workflow benötigt wird, erheblich reduzieren, weil Aufträge in auf GitHub gehosteten Runnern jedes Mal in einer bereinigten virtuellen Umgebung gestartet werden. Das Zwischenspeichern von Abhängigkeiten beschleunigt die Zeit, die zum Neuerstellen dieser Abhängigkeitsdateien benötigt wird.

Zum Zwischenspeichern von Abhängigkeiten für einen Auftrag verwenden Sie die cache-Aktion von GitHub. Mit dieser Aktion wird ein Cache abgerufen, der durch einen eindeutigen Schlüssel identifiziert wird, den Sie bereitstellen. Wenn die Aktion den Cache findet, werden die zwischengespeicherten Dateien aus dem von Ihnen konfigurierten Pfad abgerufen. Wenn Sie die Aktion cache verwenden möchten, müssen Sie bestimmte Parameter festlegen:

Parameter	Beschreibung des Dataflows	Erforderlich
Schlüssel	Bezieht sich auf den Schlüsselbezeichner, der beim Speichern und Suchen nach einem Cache erstellt wird	Ja
Pfad	Bezieht sich auf den Dateipfad auf dem Runner, der zwischengespeichert oder durchsucht werden soll	Ja
restore-keys	Besteht aus alternativen bestehenden Schlüsseln für Caches, wenn der gewünschte Cacheschlüssel nicht gefunden wird	Nein

steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

Im Beispiel oben ist path auf ~/.npm festgelegt, und key enthält das Betriebssystem des Runners und den SHA-256-Hash der Datei package-lock.json. Das Präfigieren des Schlüssels mit einer ID (npm-cache in diesem Beispiel) ist nützlich, wenn Sie das restore-keys-Fallback verwenden und über mehrere Caches verfügen.

Übergeben von Artefaktdaten zwischen Aufträgen

Ähnlich wie beim Zwischenspeichern von Abhängigkeiten in Ihrem Workflow können Sie Daten zwischen Aufträgen innerhalb des gleichen Workflows übergeben. Sie können dies mithilfe der upload-artifact- und download-artifact-Aktionen erreichen. Aufträge, die von den Artefakten eines vorherigen Auftrags abhängen, müssen warten, bis der vorherige Auftrag erfolgreich abgeschlossen wurde, bevor sie ausgeführt werden können. Dies ist nützlich, wenn Sie über eine Reihe von Aufträgen verfügen, die sequenziell auf Basis von Artefakten ausgeführt werden müssen, die aus einem vorherigen Auftrag hochgeladen wurden. job_2 erfordert z. B. job_1. Dies wird durch die Syntax needs: job_1 deutlich.

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

Im Beispiel oben sind zwei Aufträge vorhanden. job_1 schreibt Text in die Datei file.txt und verwendet dann die Aktion actions/upload-artifact@v2, um dieses Artefakt hochzuladen und die Daten für die zukünftige Verwendung im Workflow zu speichern. job_2 erfordert job_1, um abgeschlossen werden zu können. Dies ist durch die needs: job_1-Syntax bedingt. Anschließend wird die actions/download-artifact@v2-Aktion verwendet, um dieses Artefakt herunterzuladen und dann den Inhalt von file.txt auszugeben.

Aktivieren der Debugprotokollierung für Schritte in einem Workflow

In manchen Situationen liefern die Standardworkflowprotokolle nicht genügend Details, um zu diagnostizieren, warum eine bestimmte Workflowausführung, ein bestimmter Workflowauftrag oder ein bestimmter Workflowschritt fehlgeschlagen ist. In diesen Fällen können Sie zusätzliche Debugprotokollierung für zwei Optionen aktivieren: Ausführungen und Schritte. Aktivieren Sie diese Diagnoseprotokollierung, indem Sie für das Repository zwei Geheimnisse, die admin-Zugriff auf das Repository erfordern, auf true festlegen:

Für die Aktivierung der Diagnoseprotokollierung für Runner müssen Sie das Geheimnis ACTIONS_RUNNER_DEBUG im Repository, das den Workflow enthält, auf true festlegen.
Für die Aktivierung der Diagnoseprotokollierung für Schritte müssen Sie das Geheimnis ACTIONS_STEP_DEBUG im Repository, das den Workflow enthält, auf true festlegen.

Zugreifen auf die Workflowprotokolle über die Benutzeroberfläche

Damit eine Automatisierung erfolgreich verläuft, sollte der für die Automatisierung anfallende Zeitaufwand so gering wie möglich ausfallen, damit Sie sich auf das Relevante konzentrieren können. Manchmal verläuft jedoch nicht alles nach Plan, und Sie müssen überprüfen, was passiert ist. Dieser Debugprozess kann frustrierend sein. In der klaren Layoutstruktur von GitHub können Sie jedoch schnell zwischen den Aufträgen navigieren, während der Kontext des aktuellen Debugschritts erhalten bleibt. Wenn Sie die Protokolle einer Workflowausführung in GitHub anzeigen möchten, können Sie die folgenden Schritte ausführen:

Navigieren Sie in Ihrem Repository zur Registerkarte Actions.
Klicken Sie in der linken Seitenleiste auf den gewünschten Workflow.
Wählen Sie in der Liste der Workflowausführungen die gewünschte Ausführung aus.
Wählen Sie unter Jobs (Aufträge) den gewünschten Auftrag aus.
Lesen Sie die Protokollausgabe.

Wenn mehrere Ausführungen innerhalb eines Workflows vorliegen, können Sie auch den Filter Status auswählen, nachdem Sie Ihren Workflow ausgewählt haben, und ihn auf Failure (Fehler) festlegen, um nur die fehlgeschlagenen Ausführungen innerhalb dieses Workflows anzuzeigen.

Zugreifen auf die Workflowprotokolle über die REST-API

Zusätzlich zum Anzeigen von Protokollen über GitHub können Sie auch die REST-API von GitHub verwenden, um Protokolle für Workflowausführungen anzuzeigen, Workflows noch einmal auszuführen oder sogar Workflowausführungen abzubrechen. Zum Anzeigen des Protokolls einer Workflowausführung mithilfe der API müssen Sie eine GET-Anforderung an den Protokollendpunkt senden. Denken Sie daran, dass jeder Benutzer mit Lesezugriff auf das Repository diesen Endpunkt verwenden kann. Wenn das Repository privat ist, müssen Sie ein Zugriffstoken mit dem Geltungsbereich repo verwenden.

Eine GET-Anforderung zum Anzeigen eines bestimmten Workflowausführungsprotokolls würde beispielsweise diesem Pfad folgen:

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs