| name | debug-gha |
| description | Debug GitHub Actions (GHA) workflow run failures. MUST be invoked when a CI/CD run failed, a workflow is broken, steps are erroring, a job was cancelled or timed out, or the user wants to investigate what happened in a specific run. Covers fetching logs, reading job/step output, and identifying root causes.
|
Debug GitHub Actions Runs
Goal
The objective is to fix the failing run. Once you've diagnosed the cause, make
the edits that fix it, and validate them locally where you can (pre-commit, tests,
re-running the failing command) rather than relying on a fresh CI run to tell you
whether it worked.
Leave the change in the working tree for the user to review. Don't commit or push
to trigger a fresh run and "see if it's fixed": that's the user's call to make.
What GitHub Actions Is
GitHub Actions is GitHub's CI/CD platform. Workflows are YAML files in
.github/workflows/. Each workflow:
- Has triggers (
on:): push, pull_request, schedule, workflow_dispatch, etc.
- Defines jobs: parallel or sequential units of work, each running on a runner (e.g.
ubuntu-latest)
- Each job has steps: either shell
run: commands or reusable uses: actions
Conclusion values you'll see: success, failure, cancelled, skipped,
timed_out, action_required.
Investigating
A good starting point is the debug script; one command surfaces most of what you
need (always invoke it with uv):
uv run ${CLAUDE_SKILL_DIR}/scripts/debug-run.py [run-id]
It prints the run metadata, all jobs with their conclusions, any failed steps, and
the failed-step logs. If the user isn't asking about the latest failing run, find
the right run ID first with gh run list (supports --workflow, --branch,
--status, --limit).
From the failed-step logs, look for the actual error message (usually near the
bottom of the output), which step failed and what it was doing, and whether this
looks like a flaky network blip, a real code failure, or a misconfigured action.
If something points at a configuration problem, the workflow YAML lives in
.github/workflows/.
Other commands worth reaching for as the situation calls for them:
gh run view --job <job-id> --log
gh run view <run-id> --web
gh run rerun <run-id> --failed
gh run watch <run-id>
gh api repos/{owner}/{repo}/check-runs/<job-id>/annotations
Key Things to Look For
- Step that failed: the step name and number tell you where to look in the YAML
- Exit code: non-zero exit codes from shell
run: steps cause failure
- Missing secrets/env vars: often shows as empty values or auth errors
- Dependency failures: a job with
needs: won't run if the upstream job failed; its conclusion will be skipped
- Timeout:
timed_out conclusion means the job hit its timeout-minutes limit (default 360 min)
- Flaky vs. real: check if prior runs of the same workflow passed on the same branch
Reference Documentation
