Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 36 ยท Projects and Practice

Practice: Troubleshooting GitHub Actions Workflows

Diagnose broken GitHub Actions workflows: invalid YAML, workflows that never start, permission errors, missing secrets, cache and artifact problems, stuck required checks, with a log diagnoser.

Every team has the afternoon where a workflow that worked yesterday turns red, or never starts at all. Debugging Actions is a learnable skill: the failures cluster into a few families, and each has a fast first check. This lesson is a field guide. For each symptom you get the likely causes, the check that confirms them, and the fix.

Work in this order: Did it start? Did it parse? Which step failed? What did that step's log say? Most problems are found before you ever reach the fourth question.

Family 1: the workflow does not start

Symptom Likely cause Check and fix
Nothing appears in the Actions tab File is not in .github/workflows/ or lacks the .yml/.yaml extension Check the path and extension; the folder name is plural
Workflow is listed but shows no runs for a push The branches or paths filter does not match Compare the filter with the pushed branch and changed files (triggers)
Pushed to a branch, but the old version of the workflow ran schedule and workflow_dispatch use the default branch's file Merge the change to the default branch
workflow_dispatch button missing The workflow is not on the default branch, or the trigger is missing Add workflow_dispatch: and merge
Runs from a fork's pull request wait for approval First-time contributor protection A maintainer clicks "Approve and run"
Workflow disabled GitHub disables scheduled workflows after 60 days without repository activity Re-enable it in the Actions tab
No runs at all in a repository Actions are turned off in Settings -> Actions -> General Enable them or fix the allowed-actions policy

Commits whose message contains [skip ci] or [ci skip] also skip push and pull request runs, which surprises people who copy messages from other projects.

Family 2: the file does not parse

The run list shows "Invalid workflow file" with a line number. Typical causes:

  • Tabs or inconsistent indentation. YAML wants spaces. Use two per level.
  • A value that YAML misreads. on: is fine, but unquoted yes, no, 3.10 or 1e3 may become booleans or numbers. Quote versions ("3.10").
  • A colon inside a plain string, such as run: echo Result: ok. Quote the string or use a block scalar run: |.
  • Wrong nesting. steps: belongs under a job, with: under the step, not beside uses:.
  • Expression syntax. An if: that starts with ! must be quoted or wrapped: if: ${{ !cancelled() }}.
  • Unknown keys. A typo like runs_on is rejected. Use an editor with the Actions schema or the actionlint tool.

Family 3: a step fails

Open the failed job, click the red step, and read the last 20 lines first; scroll up only if the cause is not there.

"command not found" or "no such file". The tool is not installed on the runner, or the code was not checked out. Add the setup-* action, or actions/checkout. Check working-directory for monorepos.

Works locally, fails on the runner. Compare versions (Node, Python, compilers), the operating system (case-sensitive paths on Linux, backslashes on Windows) and environment variables. Print the facts: node -v; npm -v; pwd; ls -la.

Resource not accessible by integration (HTTP 403). The GITHUB_TOKEN lacks a permission. Add the needed one to the job, for example pull-requests: write or contents: write. See permissions.

Secret is empty. The name differs (case and spelling matter), the secret lives in a different environment than the job targets, or the run came from a fork pull request, where secrets are withheld by design.

Package registry 401 or 403. The token lacks packages: write, the package name is not lowercase or scoped correctly, or the package belongs to another owner (Packages).

Timeouts. A job stuck for hours usually waits on input or a deadlocked process; set timeout-minutes and make commands non-interactive (npm ci, apt-get -y).

Exit code 1 from a pipe. In a run: script, grep returning "no match" exits 1. The default shell is bash -e, which stops at the first failure and with -o pipefail fails on any failed pipe stage; handle expected failures with || true deliberately.

Family 4: caches, artifacts and outputs

  • Cache never hits. The key changes every run (for example it includes github.sha), the lock file path in hashFiles is wrong, or the cache was saved on a branch that this run cannot read.
  • Cache restored but the build is wrong. Cache only things that are safe to reuse; add the tool version to the key.
  • "Artifact not found." The upload name and download name differ, the upload step was skipped, or the jobs are in different workflow runs. Artifact names must be unique per run in v4.
  • Output is empty. The step has no id, the output name is misspelled, the job did not list it under outputs:, or the consumer job misses needs. See outputs.

Family 5: merging is blocked

  • A required check is "Expected - Waiting for status". The check name does not match any job, or the workflow was skipped by paths. Add an always-running gate job (CI project).
  • Checks are green but merging is blocked. Read the merge box: reviews, Code Owners, unresolved conversations, a stale branch, or a ruleset requirement.
  • Auto-merge never fires. A required check is still pending, or a new commit dismissed an approval.

Debugging tools

  1. Re-run with debug logging (the checkbox in the re-run dialog), or set the secret ACTIONS_STEP_DEBUG to true.
  2. Print context: echo '${{ toJSON(github) }}' is useful (never print secrets). Be careful: some fields contain untrusted text.
  3. Run locally with act, a community tool that executes workflows in Docker. It approximates, but does not replicate, GitHub's runners.
  4. Use workflow_dispatch to test without pushes, and a throwaway branch.
  5. Validate with actionlint in an editor or in CI.
  6. Reduce. Comment out jobs until the smallest failing piece remains, then read its log again.

The diagnoser below turns the first-look reading into a function: paste a log line and it suggests the family and first check. It is a small classroom rule table we wrote, so it will not recognize everything. Add rules for the failures you meet.

JS Stand-in: log line diagnoser (rule table)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the last line is unmatched: network flakiness is real, and the honest answer is "retry, then add a retry step or a mirror".

A mental checklist

  1. Started? Path, filters, default-branch rules, disabled workflow.
  2. Parsed? Indentation, quoting, schema errors.
  3. Which step? First red step, last lines of its log.
  4. What changed? Compare with the last green run: a new commit, a new action version, a runner image update, an expired token.
  5. Environment? Local versus runner differences.
  6. Permissions? Token, secrets, fork, environment.
  7. Fix and prevent: pin versions, add a timeout, add a test for the thing that broke.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A scheduled workflow was edited on a feature branch but still runs the old version. Why?

    schedule and workflow_dispatch use the workflow file on the default branch.
  2. 2. The log says 'Resource not accessible by integration'. What do you check first?

    That message means the token lacks a permission such as pull-requests: write.
  3. 3. A required check is 'waiting for status' on a docs-only pull request. Most likely cause?

    A skipped workflow does not report the check; use an always-running gate job.
  4. 4. Which is the best first move when a step fails?

    The decisive error is usually at the end of the failing step's log.
  5. 5. Why does a secret appear empty in a pull request from a fork?

    GitHub withholds secrets from fork pull requests so outsiders cannot read them.

Summary

  • Troubleshoot in order: started, parsed, failing step, its log, then what changed.
  • The common families are filters and default-branch rules, YAML mistakes, permissions and secrets, caches and artifacts, and stuck required checks.
  • Use debug logging, toJSON(github), workflow_dispatch, actionlint and reduction to find the cause.
  • Fix forward by pinning, adding timeouts and keeping a gate job.

That completes this part of the tutorial. Return to the GitHub track page to review other chapters.

Next: GitHub track overview