When a GitHub Actions workflow fails, the visible error is often only the last symptom. This guide gives you a repeatable way to validate workflow YAML, inspect job logs, reproduce commands locally, check runner differences, diagnose secrets and permissions, clear dependency caches safely, and distinguish flaky tests from genuine regressions.
Overview
GitHub Actions troubleshooting is easier when you treat a failed run as a sequence of evidence rather than as a single red status. A workflow can fail before your application code runs, during dependency installation, inside a test command, or while publishing an artifact. Each stage points to a different class of problem.
The most useful first question is: what changed between the last successful run and this run? The answer may be a commit, workflow edit, dependency lockfile, secret, permission setting, runner image, operating-system assumption, or cached installation. Record that change before making several fixes at once. Otherwise, you may repair the symptom while losing the cause.
Use this guide alongside your repository's workflow files and the current GitHub Actions documentation. Syntax, permission defaults, available runner images, action inputs, cache behavior, and usage guidance can change, so treat platform-specific details as checkpoints to verify rather than permanent assumptions.
For related repository practices, see the Git branching and pull request workflow checklist. If the failed job is testing database behavior, the SQL query debugging guide can help separate application failures from incorrect queries.
What to track
1. Validate YAML before debugging application code
Indentation, quoting, list structure, expression syntax, and misplaced keys can prevent a workflow from loading or can change what it actually does. Start with the workflow file under .github/workflows/ and compare it with a known-good version.
- Check indentation, especially beneath
jobs,steps,with,env, andpermissions. - Confirm that event filters match the branch, path, tag, or pull-request event you are testing.
- Check expressions such as
${{ secrets.NAME }}and conditional expressions for missing braces or incorrect context names. - Confirm that action inputs use the names expected by the action version you selected.
- Look for YAML values that may be interpreted unexpectedly, and quote strings containing special characters when appropriate.
After editing, use a YAML-aware editor or validator, then inspect the workflow in GitHub's interface. A file can be valid YAML while still being invalid for the Actions schema, so syntax validation and workflow-level validation are separate checks.
2. Read logs from the first meaningful failure
Do not begin with the final “process completed with exit code” line. Expand each step and find the earliest command that produced an error. Later steps may fail only because an earlier build, install, or test step did not produce the expected files.
Capture the job name, step name, command, exit code, relevant environment details, and the first useful error message. A compact incident note is more valuable than a screenshot:
Run: npm ci
Runner: Linux
Node: recorded version
First error: package or test message
Exit code: recorded value
Last known good run: commit or date
When logs contain sensitive values, redact them before sharing. Avoid adding commands that print all environment variables while investigating secrets.
3. Reproduce the exact command locally
Copy the failing command from the log and run it locally with the same working directory, package-manager mode, configuration files, and relevant environment variables. Reproducing only a broader command such as npm test may conceal which subcommand failed.
For example, if the workflow runs:
npm ci
npm run lint
npm test -- --runInBand
run those commands separately. If the command fails locally, inspect the project or dependency change. If it succeeds locally, compare the environment rather than immediately changing the test.
4. Record runner and tool differences
A hosted runner is not automatically equivalent to a developer laptop. Track the operating system, shell, architecture, runtime version, package-manager version, working directory, line-ending behavior, file-system case sensitivity, and available system dependencies.
Common portability problems include a script that works only in one shell, a filename whose capitalization differs from its import, a path separator assumption, a missing executable, or a tool version selected implicitly by the runner. Make important versions explicit where practical and print non-sensitive diagnostic information when a job begins.
5. Check secrets, variables, and permissions separately
A missing secret often appears as an authentication failure, an empty input, or a later API error. Confirm that the secret name matches exactly, that it is available for the event being tested, and that the job or environment has access to it. Pull requests from forked repositories may have different access to sensitive values than trusted branches; verify the repository's security model before changing it.
Permissions are a separate concern. If a job reads or writes repository contents, creates a release, comments on an issue, or requests an identity token, inspect the workflow's permissions block and the action's documented requirements. Grant only the access the job needs, and verify any platform defaults rather than relying on memory.
6. Treat caches as an optimization, not as a source of truth
Caching can make a build faster, but a stale or incomplete cache can make failures confusing. Check the cache key, restore-key behavior, dependency lockfile inputs, and the path being cached. If the lockfile changed but the cache key does not, the job may restore data from an earlier dependency state.
For diagnosis, temporarily bypass or invalidate the cache and run the installation from a clean state. Do not delete caching logic permanently until you know whether it affects reliability. A successful clean run followed by a failed cached run is evidence of a cache-key or cache-content problem.
7. Separate flaky tests from deterministic failures
Rerunning a failed job is useful evidence, not a complete fix. Record whether the same commit passes or fails on retry, which test failed, and whether the failure depends on timing, ordering, network access, time zones, random data, or shared state.
A deterministic failure usually reproduces under the same inputs. A flaky failure changes outcome without a relevant code change. Quarantine or retry behavior should be used carefully: retries can reduce noise but may hide a race condition. Track the test, frequency, suspected cause, and owner until the underlying issue is addressed.
Cadence and checkpoints
Use a lightweight review cadence so troubleshooting knowledge does not become stale:
- Every failed run: record the first failing step, commit, runner, command, and whether a clean retry changed the result.
- After a workflow change: review YAML structure, triggers, permissions, action versions, environment variables, and cache keys.
- Monthly: scan recurring failures, long-running jobs, repeated retries, and warnings that developers have begun ignoring.
- Quarterly: verify action documentation, runner-image assumptions, permission behavior, cache guidance, and usage or billing information in the relevant official documentation.
- After a runner-image update: compare runtime versions, installed system tools, shell behavior, and operating-system-specific tests.
Keep a small CI history table in the repository or team notes with columns for date, workflow, job, failure class, change, resolution, and follow-up. This turns repeated debugging into a searchable record.
How to interpret changes
| Symptom | Likely area | Next check |
|---|---|---|
| Workflow is not triggered | Events, branches, paths, or YAML loading | Review the trigger filters and workflow status in the repository interface. |
| Job fails before application commands | Action input, runner, permissions, or setup | Inspect the first setup step and compare its required inputs with current documentation. |
| Install fails only in CI | Runtime version, lockfile, registry access, or operating system | Run the exact install command in a clean environment and compare versions. |
| Authentication or API request fails | Secret availability, token scope, or permissions | Verify names and access without printing secret values. |
| Build fails after a cache restore | Stale or incomplete cache | Bypass the cache once and review key inputs and cached paths. |
| Different test fails on each retry | Flakiness, timing, ordering, or shared state | Run the test repeatedly, capture ordering and environment details, and isolate external dependencies. |
Be cautious with marketplace actions and third-party scripts. Review the action's repository, pinned or selected version, inputs, permissions, and maintenance signals before adding it to a production workflow. An action that hides several commands may also hide the step where an assumption breaks. For API-related jobs, the REST API testing guide provides a useful model for recording requests, authentication, validation, and reusable cases.
When a workflow runs code generated or modified with an AI coding assistant, apply a separate review of commands, permissions, dependency changes, and secret handling. The AI coding assistant code review checklist can support that review.
When to revisit
Revisit this troubleshooting guide whenever a pull-request check fails, a new workflow is introduced, a dependency or runtime is upgraded, a runner image changes, a cache strategy is modified, or a release job gains new permissions. These events alter the variables that determine whether local and CI builds behave alike.
At the end of each incident, complete this checklist:
- Identify the earliest meaningful failure and save the relevant log context.
- Record the commit, event type, runner operating system, runtime versions, and exact command.
- Reproduce the command locally or in a clean environment.
- Compare secrets, variables, permissions, and action inputs without exposing sensitive values.
- Test once with the cache bypassed if dependency state is suspect.
- Classify the result as configuration, environment, dependency, permission, cache, code, or flaky-test related.
- Document the fix and add a preventive check where it will help future runs.
Finally, review the incident record during the next monthly or quarterly checkpoint. Look for recurring job names, repeated manual retries, and failures that require tribal knowledge. Those patterns are candidates for clearer version pinning, better diagnostics, smaller jobs, more deterministic tests, or updated documentation. For broader developer productivity and online tooling, see the developer tools comparison and workflow checklist.