How to Debug a Failing GitHub Actions Workflow: A Step-by-Step Method

TL;DR#

To debug a failing GitHub Actions workflow: (1) identify the failing job and step, (2) read that step's log, working back to the first error, (3) tell code errors from configuration or environment errors, (4) reproduce the failure or enable debug logs, (5) fix it, (6) re-run only what is needed. The hard part is often not the fix, but seeing the failure in time, especially when you follow several repositories.

Step 1: Locate the failure#

Open the repository's Actions tab, then the failed run. Look for three levels:

• the workflow concerned (a file in .github/workflows/);
• the job that failed (red cross);
• the step that returned a non-zero exit code.

Later steps in a job are skipped after a failure, unless they use if: always() or if: failure(). What shows up in red is therefore a starting point, rarely the full picture.

Step 2: Read the log in the right place#

Expand the failing step. Two habits help:

• Look for the first error, not the last one: closing messages (Process completed with exit code 1) are a consequence.
• Read the lines just before it: an empty variable, a missing file or a deprecation warning often shows up there.

To search a long log, use the log viewer's search or download the run's log archive.

Step 3: Classify the cause#

Cause type	Common clues	What to try
Code / tests	Failing test, compile error, lint failure	Reproduce locally with the same command
Workflow configuration	YAML error, Unrecognized named-value, bad indentation, action not found	Validate the syntax, check action versions
Secrets and permissions	Resource not accessible by integration, empty secret, 403	Check the workflow's permissions: and available secrets (they are not passed to pull requests from forks)
Environment	Different tool version, unavailable dependency, network timeout	Pin versions, re-run to test for flakiness
Intermittent	Sometimes passes, sometimes fails	Compare previous runs (see step 6)

Step 4: Get more information#

If the log is not enough:

• Enable debug logs: set the secret or variable ACTIONS_STEP_DEBUG to true (and ACTIONS_RUNNER_DEBUG for the runner). GitHub also lets you enable debug logging when you re-run a job.
• Add targeted output: print versions and non-sensitive variables.

- name: Diagnostic
  run: |
    node --version
    echo "Ref: $GITHUB_REF"
    ls -la

• Reproduce locally: run the same command with the same tool versions as the runner.

Never print secrets in logs: GitHub masks known values, but a transformed value may still show up.

Step 5: Fix and verify#

Fix the root cause, not the symptom. A few mistakes to avoid:

• adding continue-on-error: true to "make the workflow pass": the failure is hidden, not solved;
• raising a timeout without understanding why the step is slow;
• changing several things at once, which makes the fix impossible to verify.

Push to a branch and check that the run passes before merging.

Step 6: Re-run smartly and compare with history#

GitHub lets you re-run all jobs or only the failed jobs of a run. Re-run only what is useful: it saves time and billable minutes.

Before concluding that something is fixed, compare with earlier runs of the same workflow:

• is the failure new (a recent regression) or recurring?
• does it affect a specific branch, operating system or matrix version?
• has the duration changed?

Reading the history helps tell a real bug from a one-off incident.

When you have several repositories: the real problem#

These six steps work well for a single repository. The problem changes scale as soon as you manage several projects or clients: GitHub's Actions tab is organized repository by repository. To know whether "everything is fine", you have to open each repository, often one by one, and a failure that goes unnoticed can stay unaddressed for days.

A centralized view answers that specific need: see the statuses and history of workflows across several repositories in one place, spot recurring failures, then act. That is what Squidly is for: it brings together the GitHub Actions workflows of multiple repositories and organizations so you can see, understand and act on them.

Checklist to keep#

• Identify the failing workflow, job and step
• Read up to the first error
• Classify: code, configuration, permissions, environment or intermittent
• Enable debug logs if needed
• Fix the cause, not the symptom
• Re-run only the useful jobs
• Compare with run history

Conclusion#

Debugging a GitHub Actions workflow gets fast with a method: locate, read, classify, instrument, fix, compare. If you follow several repositories, the main gain comes from visibility: spotting failures in one place, without browsing every Actions tab.

Want to follow all your workflows in one place? Discover Squidly and connect your GitHub repositories.