Tipps und Tricks zum Debuggen von GitHub Actions

Dec 7, 2025 · 4 min read

Tipps und Tricks zum Debuggen von GitHub Actions

Ein Workflow, der gestern noch funktionierte, schlägt heute mit einer kryptischen Fehlermeldung fehl. Sie haben nichts geändert. Die Logs zeigen eine Wand aus zugeklappten Steps, und irgendwo darin verbirgt sich das eigentliche Problem. Dieses Szenario frustriert jeden Engineer, der CI/CD-Pipelines wartet.

Effektives Debugging von GitHub Actions erfordert das Wissen, welche Tools existieren und wann man sie einsetzt. Dieser Leitfaden behandelt die stabilen, bewährten Techniken, die Ihnen helfen, Workflow-Fehler schnell zu diagnostizieren – ohne Zeit mit Ansätzen zu verschwenden, die nicht funktionieren.

Wichtigste Erkenntnisse

Aktivieren Sie Debug-Logging mit den Secrets ACTIONS_STEP_DEBUG und ACTIONS_RUNNER_DEBUG für tiefere Einblicke in Workflow-Fehler
Fügen Sie Diagnose-Steps hinzu, um Umgebungsdetails auszugeben, und verwenden Sie continue-on-error: true temporär, um instabile Steps zu isolieren
Validieren Sie Workflows lokal mit actionlint und nektos/act vor dem Push, um Fehler frühzeitig zu erkennen
Fixieren Sie Action-Versionen auf spezifische Tags oder SHAs, um unerwartete Fehler durch Upstream-Änderungen zu vermeiden

Debug-Logging für tiefere Einblicke aktivieren

Wenn die Standard-Logs von GitHub Actions nicht genügend Details offenbaren, aktivieren Sie Debug-Logging. Zwei Repository-Secrets steuern dieses Verhalten:

ACTIONS_STEP_DEBUG: Auf true setzen, um ausführliche Ausgaben für jeden Step zu sehen
ACTIONS_RUNNER_DEBUG: Auf true setzen für Diagnoseinformationen auf Runner-Ebene

Sie können den Debug-Modus auch aktivieren, ohne Secrets zu ändern. Wählen Sie beim erneuten Ausführen eines fehlgeschlagenen Workflows „Re-run jobs” und aktivieren Sie die Option „Enable debug logging”. Dies liefert detaillierte Traces für diesen spezifischen Durchlauf, ohne zukünftige Ausführungen zu beeinflussen.

Der Log-Viewer von GitHub unterstützt Live-Streaming und erweiterte Anzeige aktueller Logs, was es einfacher macht, lang laufende Jobs in Echtzeit zu verfolgen. Verwenden Sie die Suchfunktion innerhalb erweiterter Steps, um spezifische Fehler zu lokalisieren, anstatt durch alles zu scrollen.

Diagnose-Steps zu Ihrem Workflow hinzufügen

Manchmal benötigen Sie benutzerdefinierte Debugging-Informationen. Fügen Sie Steps hinzu, die Umgebungsdetails vor kritischen Operationen ausgeben:

- name: Debug environment
  run: |
    echo "Node version: $(node --version)"
    echo "Working directory: $(pwd)"
    echo "Event: ${{ github.event_name }}"
    env | sort

Für Steps, die unvorhersehbar fehlschlagen, verwenden Sie temporär continue-on-error: true. Dies ermöglicht die Ausführung nachfolgender Steps und zeigt, ob der Fehler sich fortsetzt oder isoliert bleibt:

- name: Potentially flaky step
  id: tests
  continue-on-error: true
  run: npm test

- name: Capture state after tests
  if: always()
  run: echo "Tests completed with status ${{ steps.tests.outcome }}"

Entfernen Sie continue-on-error, sobald Sie die Ursache identifiziert haben.

Workflows lokal validieren vor dem Push

Commits nur zum Testen der Workflow-Syntax zu pushen verschwendet Zeit und überfüllt Ihre History. Verwenden Sie actionlint, um YAML-Fehler und Expression-Fehler zu erkennen, bevor sie GitHub erreichen:

actionlint .github/workflows/

Für umfassendere lokale Tests führt nektos/act Workflows in Docker-Containern aus, die die Runner-Umgebung von GitHub annähern. Es repliziert nicht alles – Artifact-Aufbewahrung und exakte Software-Versionen unterscheiden sich – aber es validiert die Step-Ausführungsreihenfolge und erkennt offensichtliche Konfigurationsprobleme.

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Beide Tools bieten schnelle Feedback-Schleifen, die Workflow-Troubleshooting-Zyklen erheblich reduzieren.

Artifact-Verhalten verstehen

Artifacts in GitHub Actions sind Job-bezogen. Mehrere Jobs können nicht in denselben Artifact-Namen unter dem v4-System hochladen – Versuche führen zu Konflikten statt zu Zusammenführungen. Geben Sie jedem Job immer einen eindeutigen Artifact-Namen, besonders bei Matrix- oder Parallel-Builds, um Upload-Fehler zu vermeiden und vorhersehbares Abrufen sicherzustellen.

Wiederverwendbare Workflows nutzen, um Instabilität zu reduzieren

Duplizierte Workflow-Logik über Repositories hinweg führt zu Inkonsistenzen. Wenn dieselben Steps an mehreren Stellen existieren, wird das Debugging schwieriger, weil Fixes überall propagiert werden müssen.

Wiederverwendbare Workflows zentralisieren gängige Muster. Wenn Sie einen Bug beheben oder die Zuverlässigkeit an einer Stelle verbessern, profitieren alle aufrufenden Workflows davon. Dieser Ansatz macht auch das CI/CD-Debugging einfacher konsistent in Ihrer Organisation anzuwenden.

Action-Versionen fixieren und veraltete Actions vermeiden

Referenzieren Sie Actions per SHA oder spezifischen Versions-Tags statt @main oder @master. Nicht fixierte Referenzen können Workflows brechen, wenn Upstream-Änderungen auftreten:

# Bevorzugen Sie dies
uses: actions/checkout@v4

# Vermeiden Sie dies
uses: actions/checkout@main

Viele ältere Debug-Helper-Actions verwenden veraltete Node.js-Versionen. GitHub warnt in Workflow-Logs davor. Ersetzen Sie sie durch gewartete Alternativen, um unerwartete Fehler zu vermeiden, wenn GitHub schließlich die Unterstützung für Legacy-Runtimes entfernt.

Secrets in Debug-Ausgaben schützen

Debug-Logging exponiert mehr Informationen, was Risiken birgt. Geben Sie niemals Secrets direkt aus, auch nicht in Debug-Steps. GitHub maskiert bekannte Secrets, aber abgeleitete Werte oder partielle Übereinstimmungen könnten durchsickern. Überprüfen Sie Debug-Ausgaben, bevor Sie Logs öffentlich oder in Issue-Reports teilen.

Fazit

Workflow-Troubleshooting wird handhabbar, wenn Sie die richtigen Techniken kennen. Aktivieren Sie Debug-Logging für Sichtbarkeit, fügen Sie strategisch Diagnose-Steps hinzu, validieren Sie lokal mit actionlint oder act, und wahren Sie Konsistenz durch wiederverwendbare Workflows. Diese Best Practices für GitHub Actions gelten unabhängig davon, wie sich die Plattform entwickelt – sie sind Grundlagen, die CI/CD-Debugging schneller und weniger frustrierend machen.

FAQs

Zufällige Fehler stammen oft von sich ändernden externen Abhängigkeiten, wie z.B. nicht fixierten Action-Versionen, die aktualisiert werden, Package-Registry-Problemen oder Rate Limiting. Netzwerk-Timeouts und Ressourcenbeschränkungen auf Shared Runnern können ebenfalls intermittierende Fehler verursachen. Aktivieren Sie Debug-Logging und prüfen Sie, ob der Fehler mit bestimmten Zeiten oder der Verfügbarkeit externer Services korreliert.

Verwenden Sie den steps-Context mit dem id-Attribut des Steps. Weisen Sie zunächst Ihrem Step eine id zu, dann referenzieren Sie dessen Ausgaben mit der Syntax steps.step_id.outputs.output_name. Für das Ergebnis eines Steps mit continue-on-error verwenden Sie steps.step_id.outcome, das success, failure, cancelled oder skipped zurückgibt.

Ja. Verwenden Sie actionlint, um YAML-Syntax und Expressions lokal zu validieren. Für gründlichere Tests führt nektos/act Workflows in Docker-Containern aus, die die GitHub-Runner-Umgebung simulieren. Obwohl act nicht jedes GitHub-Feature replizieren kann, erkennt es die meisten Konfigurationsfehler und validiert die Step-Ausführungsreihenfolge vor dem Push.

ACTIONS_STEP_DEBUG aktiviert ausführliche Ausgaben für einzelne Workflow-Steps und zeigt detaillierte Informationen über die Ausführung jeder Action. ACTIONS_RUNNER_DEBUG liefert Diagnoseinformationen auf niedrigerer Ebene über den Runner selbst, einschließlich Umgebungs-Setup und interner Operationen. Für die meisten Debugging-Szenarien bietet ACTIONS_STEP_DEBUG ausreichende Details.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.