Verwalten und Debuggen von Workflows in GitHub-Aktionen

10 Minuten

Denken Sie daran, dass Ihr Ziel darin besteht, den Codebuild- und Veröffentlichungsprozess zu automatisieren, damit Features jedes Mal aktualisiert werden, wenn ein Entwickler der Codebasis eine Änderung hinzufügt.

Um diesen Prozess zu implementieren, erfahren Sie, wie Sie:

Identifizieren Sie das Ereignis, das einen Workflow ausgelöst hat.
Verwenden Sie GitHub Actions-Workflow-Protokolle.
Speichern und Zugriff auf Build-Artefakte.
Automatisieren Sie das Hinzufügen einer Bezeichnung zu einer Pullanforderung nach einer Überprüfung.

Identifizieren des Ereignisses, das einen Workflow ausgelöst hat

Das Verständnis, was einen GitHub-Aktionen-Workflow ausgelöst hat, ist für das Debuggen, Überwachen und Verbessern von CI/CD-Pipelines von entscheidender Bedeutung. Die Art der Auslöser umfasst einen Push in einen Branch, einen erstellten oder aktualisierten Pull Request, einen geplanten Auftrag oder eine manuelle Abfertigung. Sie können das auslösende Ereignis identifizieren, indem Sie die Workflowausführung, die Repositoryänderungen und das zugehörige GitHub-Problem oder pull-Anforderung untersuchen.

Diagramm, das verschiedene Workflowtrigger in GitHub-Aktionen zeigt, z. B. Push, Pullanforderung, Zeitplan und manuelle Versendung.

Was ist ein Workflowtrigger?

Ein Workflowtrigger ist ein Ereignis, das dazu führt, dass ein Workflow ausgeführt wird. GitHub unterstützt verschiedene Arten von Triggern, einschließlich:

push oder pull_request (basierend auf Codeänderungen)
workflow_dispatch (manueller Auslöser)
schedule (Cronjobs)
repository_dispatch (externe Systeme)
Problem-, Diskussions- und Pull Request-Ereignisse (z. B. issues.opened, pull_request.closed)

Identifizieren des Triggerereignisses

Sie können ein Workflowtriggerereignis auf mehrere Arten identifizieren:

Nutzen Sie die GitHub Actions-Benutzeroberfläche.
1. Wählen Sie in Ihrem Repository die Registerkarte "Aktionen " aus.
2. Wählen Sie einen Workflow-Durchlauf aus.
Ein Ereignistyp, wie z. B. push, pull_request oder workflow_dispatch, wird am Anfang der Zusammenfassung des Workflowlaufs angezeigt.
Verwenden Sie github.event_name in den Protokollen oder in einem Workflow.
- GitHub macht Kontextdaten während einer Workflowausführung verfügbar. Die github.event_name Variable teilt Ihnen mit, welches Ereignis den Workflow ausgelöst hat.
- Sie können die Informationen in einem Schritt zum Debuggen drucken:
```
-name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"
```
Verwenden von Workflowausführungsdetails:
- Wenn Sie den Workflow programmgesteuert prüfen, z. B. mithilfe der API, enthält das Ausführungsobjekt eine event Eigenschaft, die den Trigger angibt.
- Sie können den Commit Secure Hash Algorithm (SHA), Akteur und Zeitstempel finden, um zu verfolgen, was den Auslöser verursacht hat.

Ableiten des Triggers aus Repositoryeffekten

Möglicherweise haben Sie keinen direkten Zugriff auf die Workflowausführung, aber Sie möchten dennoch ableiten, was den Workflow basierend auf Repositoryaktivitäten ausgelöst hat:

Beobachtetes Verhalten	Auslöserereignis
Ein neuer Commit wurde per Push an `main` übertragen und der Workflow wurde ausgeführt.	`push`-Ereignis
Eine Pullanforderung wurde geöffnet oder aktualisiert.	`pull_request`-Ereignis
Ein Mitwirkender hat manuell einen Workflow ausgeführt.	`workflow_dispatch`
Der Workflow wird täglich zu einem bestimmten Zeitpunkt ausgeführt.	`schedule` (Cron)
Der Workflow wurde nach einem externen Dienstaufruf ausgeführt.	`repository_dispatch`
Der Workflow wurde ausgeführt, wenn einem Problem eine Bezeichnung oder ein Kommentar hinzugefügt wurde.	`issues.*`-Ereignis

Durch Überprüfen von Zeitstempeln, Pullanforderungsaktivitäten und Commit-Verlauf können Sie häufig bestimmen, welche Aktion den Workflow ausgeführt hat.

So fassen Sie zusammen, wie Sie ermitteln, was einen Workflow ausgelöst hat:

Überprüfen Sie die Workflowausführungszusammenfassung auf der Registerkarte "Aktionen ".
Drucken oder protokollieren Sie github.event_name im Workflow, um die Sichtbarkeit zu verbessern.
Vergleichen Sie Zeitstempel und Repositoryaktivitäten (Commits, Pullanforderungen, Probleme), um den Trigger abzuleiten.
Verwenden Sie den vollständigen event Kontext für eine tiefere Untersuchung.

Diese Methoden helfen Ihnen beim Debuggen, Überwachen und Verbessern der Workflowsicherheit in Ihren Entwicklungs- und Bereitstellungspipelinen.

Verständnis eines Workfloweffekts durch das Lesen der Konfigurationsdatei

Um die Auswirkungen eines Workflows aus der Konfigurationsdatei zu verstehen, analysieren Sie die Struktur und den Inhalt der unter .yml gespeicherten .github/workflows/-Datei.

Die Workflowkonfigurationsdatei gibt die folgenden Informationen zum Workflow an:

Ausführungszeit (im on-Abschnitt).
Was es tut (in jobs und steps).
Ausführungsort (der runs-on-Abschnitt).
Ausführungsgrund (der Zweck, z. B. Testen, Bereitstellen oder Linten).
Verhalten in bestimmten Bedingungen (Umgebung, Filter, Logik).

Interpretation eines Workflow-Effekts

Identifizieren Sie den Auslöser.

Informationen dazu, welche Aktion den Workflow initiiert hat, finden Sie im on Abschnitt des Workflows.

Beispiel:
```
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
```
Dieser Beispielworkflow:
- Wird automatisch ausgeführt, wenn Code an die Hauptzweigung (push) verschoben wird.
- Wird ausgeführt, wenn eine Pullanforderung erstellt oder aktualisiert wird (pull_request).
- Kann manuell von einem Benutzer (workflow_dispatch) ausgelöst werden.
Identifizieren Sie die Workflowaufträge und -schritte.

Informationen zum Ermitteln der Funktionsweise des Workflows finden Sie in den jobssteps Abschnitten des Workflows.

Beispiel:
```
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
```
Dieser Beispielworkflow:
- Verwendet eine virtuelle Linux-Umgebung (runs-on).
- Checkt den Code des Repositorys aus (steps>name).
- Installiert Projektabhängigkeiten (steps>name).
- Führt automatisierte Tests (steps>name) aus.
Bewerten sie den Zweck und das Ergebnis des Workflows.

Durch Lesen der Konfigurationsdatei können Sie das beabsichtigte Ergebnis des Workflows beschreiben:

"Dieser Workflow ist eine kontinuierliche Integrationspipeline (CI). Dadurch wird sichergestellt, dass jeder neue Code, der per Pullanforderung an das Repository gesendet oder übermittelt wird, automatisch getestet wird. Wenn Tests fehlschlagen, zeigt die GitHub-Workflowbenutzeroberfläche dieses Ergebnis an, um die Codequalität aufrechtzuerhalten."
Identifizieren oder Festlegen optionaler Features, die sich auf die Ausführung des Workflows auswirken:
- env legt Umgebungsvariablen fest.
- if Fügt bedingte Logik hinzu, um bestimmte Schritte nur auszuführen, wenn Kriterien erfüllt sind.
- timeout-minutes oder continue-on-error Festlegen der Workflowausführung und Fehlerbehandlung.

Diagnostizieren einer fehlgeschlagenen Workflowausführung

Wechseln Sie in Ihrem Repository zur Registerkarte "Aktionen ".
Suchen Sie die fehlgeschlagene Ausführung (in der Regel durch ein rotes X angegeben).
Wählen Sie den fehlgeschlagenen Workflow aus, um die Ausführungszusammenfassung zu öffnen.
Überprüfen Sie in den Workflowprotokollen den Fehler.
1. Erweitern Sie in der Ausführungszusammenfassung jeden Auftrag und Schritt, bis Sie denjenigen gefunden haben, bei dem ein Fehler auftritt.
2. Wählen Sie den Auftrag oder Schritt aus, um seine Protokolle anzuzeigen.
3. Suchen nach:
  - Fehlermeldungen
  - Stapelablaufverfolgungen
  - Exitcodes
Ein fehlgeschlagener Test könnte beispielsweise npm ERR! Test failed oder exit code 1 anzeigen.
Überprüfen Sie die Workflowkonfigurationsdatei.

Verwenden Sie die .yml Datei, um Folgendes zu bestimmen:
- Was versuchte jeder Schritt zu tun?
- Wenn Umgebungsvariablen (env) oder Bedingungen (if) vorhanden sind, die sich auf die Ausführung auswirken.
- Wenn der Fehler auf eine fehlende Abhängigkeit, einen Syntaxfehler oder einen falsch konfigurierten Schritt zurückzuführen ist.
Wenn ein Schritt fehlschlägt, überprüfen Sie die folgenden Ursachen:
- Wurden Abhängigkeiten im vorherigen Schritt erfolgreich installiert?
- Sind Testdateien vorhanden, und bestehen sie lokal?

Häufige Fehlerszenarien

In der folgenden Tabelle werden allgemeine Workflowfehlerszenarien beschrieben:

Symptom	Wahrscheinliche Ursache
Ein Schritt schlägt fehl und gibt `command not found`l zurück.	Fehlende Abhängigkeit oder falsche Einrichtung
`npm install` schlägt fehl.	Beschädigte `package-lock.json` Datei oder ein Netzwerkproblem
Ein Testschritt schlägt fehl.	Komponententestprobleme, fehlende Konfigurationsdatei oder ungültige Testsyntax
`Permission denied` wird angezeigt.	Falsche Dateiberechtigungen oder fehlende geheime Schlüssel

Wie man auf Workflow-Protokolle in GitHub zugreift

Wechseln Sie in Ihrem Repository zur Registerkarte "Aktionen ".
Wählen Sie in der Liste der Workflows den relevanten Workflow aus.

Wenn Ihre .yml Datei beispielsweise den folgenden Code aufweist, wird in der Liste ein Link mit dem Titel CI-Workflow angezeigt:
```
name: CI Workflow
```
Wählen Sie einen bestimmten Lauf aus.

Wählen Sie in der Liste der Ausführungen, die den Status anzeigen, den Zeitstempel oder die Commit-Nachricht der spezifischen Ausführung aus, die Sie untersuchen möchten.
Erweitern Sie jede Aufgabe und jeden Schritt.

Auf der Ausführungsübersichtsseite werden Aufträge angezeigt, die in der Workflowdatei definiert sind, wie zum Beispiel Aufbau oder Test.
1. Wählen Sie einen Auftrag aus, um ihn zu erweitern.
2. Erweitern Sie innerhalb des Auftrags einzelne Schritte, z. B. „Installieren von Abhängigkeiten“ oder „Ausführen von Tests“.
Protokollausgabe anzeigen.

Um die vollständige Protokollausgabe anzuzeigen, einschließlich Konsolenprotokollen, Fehlermeldungen und Debuginformationen, wählen Sie einen Workflowschritt aus. Sie können die Protokolle kopieren, durchsuchen und herunterladen.

In der folgenden Tabelle sind die Schritte zusammengefasst, die Sie für den Zugriff auf Workflowprotokolle ausführen:

Maßnahme	Zweck
Registerkarte „Aktionen“	Alle Workflowausführungen anzeigen.
Auswählen des Workflownamens	Der Filter wird nach Workflow ausgeführt.
Auswählen einer Ausführung	Zeigen Sie bestimmte Auftrags- und Schrittergebnisse an.
Schritte erweitern	Detaillierte Protokolle anzeigen.
Protokolle herunterladen	Laden Sie Protokolle für die Offline-Diagnose oder die Fehlerbehebung im Team herunter.

Aktionsprotokolle für den Build

Wenn ein Workflow ausgeführt wird, wird ein Protokoll erstellt, das die Details zu dem, was passiert ist und alle Fehler oder Testfehler enthält.

Wenn ein Fehler auftritt oder ein Test fehlschlägt, wird in den Protokollen ein rotes X anstelle eines grünen Häkchens angezeigt. Sie können die Details des Fehlers oder Ausfalls prüfen, um zu untersuchen, was passiert ist.

Screenshot des GitHub Actions-Protokolls mit Details zu einem fehlgeschlagenen Test.

Arbeiten mit Artefakten

Wenn ein Workflow etwas anderes als einen Protokolleintrag erzeugt, wird das Produkt als Artefakt bezeichnet. Beispielsweise erzeugt der Node.js Build einen Docker-Container, der bereitgestellt werden kann. Der Container ist ein Artefakt, das Sie mithilfe der Aktionen/Uploadartefaktaktion in den Speicher hochladen können. Sie können das Artefakt später aus dem Speicher herunterladen, indem Sie Aktionen/Downloadartefakte verwenden.

Durch das Speichern eines Artefakts bleibt es zwischen Aufträgen erhalten. Jeder Auftrag verwendet eine neue Instanz eines virtuellen Computers, sodass Sie das Artefakt nicht wiederverwenden können, indem Sie es auf dem virtuellen Computer speichern. Wenn Sie Ihr Artefakt in einem anderen Job benötigen, können Sie das Artefakt in einem Job auf den Speicher hochladen und es für den anderen Job herunterladen.

Artefaktspeicher

Artefakte werden im Speicherplatz auf GitHub gespeichert. Der Speicherplatz ist für öffentliche Repositorys kostenlos, und je nach Konto ist ein Teil des Speichers kostenlos für private Repositorys. GitHub speichert Ihre Artefakte 90 Tage lang.

Beachten Sie im folgenden Workflowausschnitt, dass in der actions/upload-artifact@main Aktion ein path Attribut vorhanden ist. Der Wert dieses Attributs ist der Pfad zum Speichern des Artefakts. In diesem Beispiel geben Sie "öffentlich/" an, um alles in ein Verzeichnis hochzuladen. Wenn Sie nur eine einzelne Datei hochladen möchten, verwenden Sie etwas wie "öffentlich/mytext.txt".

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Um das Artefakt zum Testen herunterzuladen, muss der Build erfolgreich abgeschlossen und das Artefakt hochgeladen werden. Im folgenden Code geben Sie an, dass der Testauftrag vom Buildauftrag abhängt.

test:
    needs: build
    runs-on: ubuntu-latest

Im folgenden Workflowausschnitt laden Sie das Artefakt herunter. Das Artefakt kann nun zu Testzwecken im Testauftrag verwendet werden.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Weitere Informationen zur Verwendung von Artefakten in Workflows finden Sie unter Speichern von Workflowdaten als Artefakte.

Automatisieren von Rezensionen in GitHub mithilfe von Workflows

Zusätzlich zum Starten eines Workflows über GitHub-Ereignisse wie push und pull-requestkönnen Sie einen Workflow nach einem Zeitplan oder nach einem Ereignis außerhalb von GitHub ausführen.

Möglicherweise möchten Sie, dass ein Workflow erst ausgeführt wird, nachdem ein Benutzer eine bestimmte Aktion abgeschlossen hat, z. B. nachdem ein Prüfer eine Pullanforderung genehmigt hat. Für dieses Szenario können Sie auf pull-request-review auslösen.

Eine weitere Aktion, die Sie ausführen können, ist das Hinzufügen einer Bezeichnung zur Pullanforderung. Verwenden Sie in diesem Fall die „pullreminders/label-when-approved-action“-Aktion.

Beispiel:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

env Im Block legen Sie die Umgebungsvariablen für die Aktion fest. Sie können z. B. die Anzahl der genehmigenden Personen festlegen, die zum Ausführen des Workflows erforderlich sind. In diesem Beispiel ist es eins. Die secrets.GITHUB_TOKEN Authentifizierungsvariable ist erforderlich, da die Aktion Änderungen am Repository vornehmen muss, indem eine Bezeichnung hinzugefügt wird. Schließlich geben Sie den Namen des hinzuzufügenden Etiketts ein.

Das Hinzufügen einer Bezeichnung kann ein Ereignis sein, das einen anderen Workflow startet, z. B. eine Zusammenführung. Wir behandeln dieses Ereignis im nächsten Modul, das die Verwendung der kontinuierlichen Zustellung in GitHub-Aktionen beschreibt.

Feedback

War diese Seite hilfreich?