When a GitHub Actions workflow fails, the visible error is often several steps removed from the actual cause. This guide gives you a repeatable troubleshooting process, copy-ready workflow snippets, and a review checklist for YAML syntax, job dependencies, permissions, secrets, matrix builds, artifacts, and caching. Use it when a pull request check fails, a release job is skipped, or CI behaves differently from your local build.
Overview
A reliable diagnosis starts by separating four questions: did GitHub read the workflow, did it start the intended job, did the runner execute each step, and did the application or test command pass? These layers produce different failures, so changing code before identifying the layer can make the investigation slower.
- Workflow parsing: YAML indentation, quoting, expressions, and unsupported keys can prevent a workflow from loading.
- Job selection: branch filters, event conditions, matrix settings, and
needsrelationships can skip jobs. - Runner execution: operating-system differences, missing tools, permissions, environment variables, and shell behavior can stop a step.
- Application execution: dependency installation, tests, builds, and deployment commands can fail even when the workflow itself is valid.
Start with the run summary and identify the first failed step, not merely the final red status. Expand the log around that step, record the event that triggered the run, and compare the commit, branch, runner operating system, and runtime versions with the environment used locally.
What to track
Keep a small troubleshooting record for recurring failures. The goal is not to collect every log line; it is to track the variables most likely to change between a successful run and a failed one.
1. Workflow and trigger details
Record the workflow file, event name, branch or tag, and whether the run came from a pull request, push, manual dispatch, or another event. Conditions can make a workflow appear inconsistent when it is actually responding to different event payloads.
For example, this job runs only when the first job succeeds:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test
package:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm run build
If test is skipped or fails, package will not run normally. Inspect the dependency graph before treating a skipped job as an independent error.
2. YAML structure and expressions
YAML is sensitive to indentation and data types. A value that looks like a number, boolean, or special string may not behave as intended. Keep related keys aligned, quote values containing punctuation, and make expressions easy to inspect.
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
checks:
runs-on: ubuntu-latest
steps:
- name: Check out source
uses: actions/checkout@v4
- name: Show branch context
run: echo "Ref is $GITHUB_REF"
- name: Run checks
run: npm test
When a workflow fails before a job begins, inspect the file first. Temporarily simplify complex expressions, multiline commands, and nested conditionals. Reintroduce them one at a time after the minimal workflow loads successfully.
3. Runtime and dependency versions
Track the runner operating system, language version, package-manager version, lockfile, and installation command. A local build may use a globally installed tool or a cached dependency that the runner does not have.
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
For Python, make the interpreter and dependency installation equally explicit:
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install dependencies
run: python -m pip install -r requirements.txt
- name: Run tests
run: python -m pytest
Use versions that your project supports, and treat action versions and runner labels as reviewable dependencies. A routine dependency audit can complement this process; see the NPM dependency update guide when package changes are part of the failure.
4. Permissions, secrets, and outputs
A workflow can be syntactically correct and still fail because a token cannot read, write, publish, or comment. Grant only the permissions required by the job and define them close to the workflow or job that needs them.
permissions:
contents: read
jobs:
release:
permissions:
contents: read
packages: write
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Publish package
env:
TOKEN: ${{ secrets.PACKAGE_TOKEN }}
run: ./scripts/publish.sh
Do not print secret values while debugging. Check whether the secret is available for the event that triggered the run, whether its name matches exactly, and whether the command expects an environment variable, a file, or a command-line option. If a value is optional, add an explicit validation step that reports its presence without revealing it.
5. Matrix combinations, artifacts, and caches
Matrix builds multiply the number of environments that can fail. Record the exact operating system, runtime version, and matrix values for the failing combination.
strategy:
fail-fast: false
matrix:
node: [18, 20]
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm test
For artifacts, verify that the producing step created files at the path you upload. For caches, track the key, restore keys, lockfile, and whether the cache was restored or newly created. A cache can preserve an outdated or incompatible dependency state, but disabling caching is a diagnostic experiment rather than a permanent fix.
Cadence and checkpoints
Use a lightweight review cadence instead of waiting for a major outage.
At every failed run
- Open the earliest failed step and copy its concise error message.
- Check the event, branch, commit, runner, matrix values, and changed workflow files.
- Separate an infrastructure or permission error from a test or build error.
- Retry only after recording what changed; otherwise a passing retry can hide a flaky condition.
Monthly or quarterly
- Review action versions, runtime versions, runner labels, and package-manager commands.
- Remove unused secrets, permissions, matrix entries, and obsolete workflow files.
- Check whether cache keys still include the files that determine dependency state.
- Run important workflows from their normal pull-request, push, and release paths.
- Confirm that artifact names, upload paths, and retention assumptions still match the project’s needs.
Keep these checks in the same change-review process as application dependencies. A workflow is executable project code, so a small, documented update is usually easier to diagnose than a large migration performed under deadline pressure.
How to interpret changes
Look for correlation between a new failure and the smallest set of changed variables. If the same commit passes on one operating system but fails on another, inspect shell syntax, path separators, file permissions, and platform-specific tools. If every matrix entry fails at dependency installation, inspect the lockfile, registry access, package-manager command, or runtime version before examining application tests.
A skipped job usually calls for a condition or dependency review, not a code rollback. Check if expressions, branch filters, event payload assumptions, and needs. A job that never starts cannot produce a useful application log.
When a cache-related failure disappears with caching disabled, compare the cache key with the dependency inputs. Include the relevant lockfile hash in the key and avoid restoring a cache created for a materially different runtime or platform. If the failure remains, the cache was probably not the primary cause.
When a permission error appears after a workflow change, inspect the effective permissions at the job level and the token or secret used by the action. Do not solve an authorization problem by broadly granting write access. Narrow permissions make future failures easier to explain.
For errors outside Actions itself, follow the application signal. A failing API call may be a CORS or authentication issue, while a malformed fixture may be easier to inspect with a JSON formatter. Related debugging references include the CORS troubleshooting guide, HTTP status code guide, and JSON formatter and validator guide.
When to revisit
Revisit this troubleshooting checklist whenever a workflow is migrated, a runner image or runtime changes, an action version is updated, a secret or permission is modified, or a release pipeline is expanded. Also review it after repeated flaky runs, unexplained cache misses, a new matrix combination, or a change from local scripts to CI commands.
For a practical next step, choose one representative workflow and create a short maintenance note containing:
- The events and branches that should trigger it.
- The supported runtime and operating-system combinations.
- The permissions and secrets each job requires.
- The expected artifact paths and cache inputs.
- The first command to run locally when each major step fails.
Then test the workflow from a clean checkout, inspect one successful run, and save the diagnosis for the next failure. If YAML or dependency behavior is involved, compare the workflow with the project’s normal code and package-management conventions. If the problem is part of a broader type or source error, the TypeScript error guide and Git recovery guide can help with adjacent investigations. A quarterly review, plus a review after every meaningful CI change, keeps this checklist useful rather than merely documenting an old incident.