When a GitHub Actions workflow fails, the visible error is often only the last symptom. This guide gives you a repeatable way to read logs, reproduce jobs, inspect permissions and secrets, diagnose cache and matrix problems, and confirm that a deployment produced the build you intended. It also provides a maintenance routine so your CI pipeline remains understandable as dependencies, runner images, and deployment requirements change.
Overview
GitHub Actions debugging is most effective when you treat a workflow as a sequence of observable inputs and outputs rather than as one large build command. A job receives an event, permissions, variables, secrets, source code, dependencies, and sometimes artifacts from another job. It then runs on a selected runner with a particular operating-system image and toolchain. A failure can originate in any of those layers.
Start by identifying the smallest failed unit:
- Workflow: Did the workflow trigger at all, and did the intended branch or event match?
- Job: Was the job skipped because its condition evaluated to false?
- Step: Which command returned a nonzero exit status?
- Input: Was a secret, variable, artifact, dependency, or permission missing?
- Environment: Did the runner, operating system, Node.js version, package manager, or deployment environment differ from local development?
Do not begin by rerunning the workflow repeatedly without changing or inspecting anything. A rerun may pass because a service recovered, a cache was refreshed, or a race condition disappeared. Record the original run, commit, event type, matrix values, and failing step first. That information makes intermittent problems easier to compare.
For related debugging work, see the guide to production JavaScript source maps when a deployment succeeds but runtime errors are difficult to trace.
What to track
Use the failure symptom as a starting point
| Symptom | Likely area | First checks |
|---|---|---|
| Workflow never starts | Trigger or repository configuration | Event name, branch filters, file paths, workflow location, and whether the event is eligible to run the workflow |
| Job is skipped | Conditions or dependencies | if expressions, needs results, event context, matrix values, and output names |
| Command works locally but fails in CI | Environment mismatch | Runtime versions, working directory, environment variables, lockfile usage, and operating-system differences |
| Dependencies are unexpectedly old | Cache or installation logic | Lockfile, cache key, restore behavior, package-manager command, and cache invalidation inputs |
| Secret appears empty | Scope or permissions | Secret name, repository or environment scope, fork context, environment approval, and masking behavior |
| Deployment runs the wrong build | Artifact, branch, or concurrency flow | Commit SHA, artifact name, upload and download steps, deployment target, and overlapping runs |
Track workflow identity
For every failed run, note the workflow file, run number, commit SHA, triggering event, source branch, actor, and job or matrix combination. A pull request run may have different permissions and secrets from a run on the default branch. A manually dispatched run may also use different inputs. These details explain many apparent inconsistencies.
Add explicit diagnostic output that is safe to disclose. For example, print the runtime version, package-manager version, current directory, and selected non-sensitive configuration values:
node --version
npm --version
pwd
printf 'CI=%s\n' "$CI"
printf 'Ref=%s\n' "$GITHUB_REF"
printf 'SHA=%s\n' "$GITHUB_SHA"Never print secret values, token fragments, complete authorization headers, or untrusted payloads that could contain credentials. A masked value can still create confusing logs if it is transformed or concatenated, so keep diagnostic output deliberately narrow.
Track dependency and cache inputs
A dependency cache should be tied to the files that define the dependency graph, usually a lockfile and the relevant operating system or runtime. If a cache key does not change when the lockfile changes, a successful restore may contain an older dependency set. Conversely, a key that changes on every run prevents useful reuse.
Check whether the workflow installs from the lockfile rather than silently resolving new versions. Keep installation, caching, and build commands visible as separate steps while debugging. This makes it easier to distinguish a cache restore problem from a package installation problem.
Track secrets, permissions, and environments
When GitHub Actions secrets are not working, first verify the exact secret name and where it is stored. Repository secrets, organization-level secrets, and environment secrets can have different availability rules. A job may also need to declare its deployment environment before environment-scoped values become available.
Inspect the workflow's permissions block and grant only what the job needs. A checkout operation, release operation, artifact operation, or deployment action may require different access. If a token is unavailable, distinguish between an absent secret, an empty value, and a token that exists but lacks permission. Log whether a value is present without revealing it, for example by testing its length or using a boolean expression.
Track artifacts and job outputs
For multi-job workflows, document the handoff between jobs. The producing job should upload an artifact with a stable, descriptive name, and the consuming job should download that same artifact. Record which commit generated it. If a deployment job rebuilds the application instead of consuming the tested artifact, it can deploy code that was not the code validated earlier.
Cadence and checkpoints
Use a small maintenance cadence instead of waiting for a production failure.
On every failed run
- Open the failed job and expand the first meaningful error, not merely the final summary.
- Read several lines before the error to identify the command and its inputs.
- Check the event, branch, commit, matrix values, and runner environment.
- Compare the failing run with the most recent successful run.
- Decide whether the cause is code, configuration, dependency resolution, infrastructure, or an external service.
- Rerun only after capturing the original evidence.
Monthly or quarterly
Review workflow files for stale action references, unclear step names, redundant setup commands, and permissions broader than necessary. Confirm that runtime versions and package-manager commands match the project's supported development setup. Examine cache hit and miss behavior, artifact retention needs, concurrency settings, and the list of required secrets.
Also perform a controlled test of a failure path. Examples include temporarily using an invalid build command in a branch, verifying that a failed test prevents deployment, or confirming that a missing secret produces a clear error. Do this without exposing credentials or changing the production target.
After platform or project changes
Revisit the workflow whenever you change the framework, package manager, lockfile format, deployment provider, runner operating system, build output directory, authentication model, or branch strategy. Marketplace actions and setup actions should be reviewed when their major version or configuration changes. Treat a runner-image change as an environment change even when application code is untouched.
How to interpret changes
Read logs from the first divergence
Compare a failed run to a known-good run and find the first meaningful difference. A later error may be a consequence. For example, a missing environment variable can cause a configuration file not to load, which then appears as a framework build error. A cache miss is not automatically a failure; it may simply mean the dependency graph changed. The important question is whether installation completed from the intended lockfile afterward.
Separate skipped from failed
A skipped job often indicates intentional condition logic rather than a broken command. Review expressions involving github.ref, event names, outputs, and needs. Remember that a dependent job may be skipped when an earlier job fails, even if the dependent job's own commands are valid. Make job names and conditions descriptive enough that the run summary explains the decision.
Diagnose matrix failures independently
A matrix creates multiple job variations. One operating system, runtime version, browser, or feature flag may fail while the others pass. Always record the matrix values for the failing instance. Avoid fixing a matrix failure by removing that combination unless it is intentionally unsupported and documented. If setup differs by matrix value, make the conditional steps explicit.
Distinguish cache problems from source problems
To test a suspicious cache, run a temporary diagnostic branch with a changed cache key or caching disabled. If the build passes with a fresh installation, inspect the key, lockfile path, package-manager cache path, and restore behavior. Do not permanently delete caching as the first response; determine why an old or incompatible cache was accepted.
Trace deployments end to end
For a deployment that appears to publish the wrong build, write the expected commit SHA into the build or artifact metadata where practical. Then verify the SHA at checkout, artifact upload, artifact download, and deployment. Check whether multiple workflow runs can deploy concurrently. A concurrency policy may cancel an older run or allow a later run to supersede it; either behavior should be deliberate and visible in the workflow design.
If the issue is connected to domains or verification rather than the build itself, consult the DNS records guide for web developers. For callback and delivery failures, the webhook debugging guide covers a related evidence-gathering process.
When to revisit
Keep this checklist with the repository and revisit it at least monthly or quarterly, depending on how often the project deploys. Return immediately after a failed pull request check, a runner-image update, a runtime upgrade, a package-manager migration, a cache anomaly, a new deployment target, or a change to repository and environment permissions.
Before editing a workflow, capture its current behavior. Save a successful run link, the expected artifact or commit, the required secrets and permissions, and the commands used for local reproduction. After editing, test the smallest affected path first, then run the complete build and deployment checks.
A practical incident note should answer five questions:
- What event started the run?
- Which job, step, and matrix value failed or skipped?
- What changed from the last successful run?
- What evidence confirmed the root cause?
- What preventive check, documentation update, or monitoring item was added?
Use the same discipline for recurring project setup work. A documented TypeScript configuration and script layout, such as the one covered in this TypeScript project setup guide, reduces the gap between local commands and CI commands. Clear inputs, reproducible installs, narrow permissions, traceable artifacts, and scheduled reviews make failed GitHub Actions workflows faster to diagnose and less likely to become recurring surprises.