How to Debug a Failing GitHub Actions Workflow
When a workflow fails for no obvious reason, these techniques surface the real cause fast.
Most CI debugging is about getting more signal: more logs, an interactive shell, or a local reproduction.
Turn on debug logs
Set repo secrets ACTIONS_STEP_DEBUG: true and ACTIONS_RUNNER_DEBUG: true, then re-run to get verbose logs.
Get an interactive shell
Add a mxschmitt/action-tmate step to open an SSH session into the runner and poke around live.
Read above the failure
The exit line (e.g. ELIFECYCLE, exit 137) is a wrapper - the real error is in the lines just above it.
Reproduce locally
Tools like act run workflows locally for fast iteration without pushing commits.
Related guides
Exit Codes and Signals in CI/CD: A Practical GuideA practical guide to process exit codes and signals in CI/CD - what 1, 2, 124, 126, 127, 130, 137, and 143 me…
Why Is My CI So Slow? A Diagnostic ChecklistDiagnose slow GitHub Actions: no caching, serial tests, cold starts, oversized Docker context, and chatty tri…
CI Exit Code Lookup: What Does This Exit Code Mean?Instant lookup for CI/CD process exit codes - enter a code (137, 127, 143…) to see what it means, whether it…
How to Retry a Failed Step or Job in GitHub ActionsHow to retry failed GitHub Actions steps and jobs - manual re-runs, retry actions with backoff, and automatic…