| name | ci-fix |
|---|---|
| description | Fix GitHub Actions CI failures using GitHub CLI (gh): inspect runs/logs, identify root cause, patch workflows/code, rerun jobs, and summarize verification. Use when GitHub Actions CI is failing or needs diagnosis. |
CI fix (GitHub Actions)
Goal
- Get CI green quickly with minimal, reviewable diffs.
- Use
ghto locate failing runs, inspect logs/artifacts, rerun jobs, and confirm the fix.
Inputs to ask for (if missing)
- Repo (
OWNER/REPO) and whether this is a PR or branch build. - Failing run URL/ID (or PR number / branch name).
- What "green" means (required workflows? allowed flaky reruns?).
- Any constraints (no workflow edits, no permission changes, no force-push, etc.).
Workflow (checklist)
1) Confirm gh context
- Auth: gh auth status
- Repo: gh repo view --json nameWithOwner -q .nameWithOwner
- If needed, add -R OWNER/REPO to all commands.
- If gh is not installed or not authenticated, tell the user and ask whether to install/authenticate or proceed by pasting logs/run URLs manually.
2) Find the failing run
- If you have a run URL, extract the run ID: .../actions/runs/<id>.
- Otherwise:
- Recent failures: gh run list --limit 20 --status failure
- Branch failures: gh run list --branch <branch> --limit 20 --status failure
- Workflow failures: gh run list -w <workflow> --limit 20 --status failure
- Open in browser: gh run view <id> --web
3) Pull the signal from logs
- Job/step overview: gh run view <id> --verbose
- Failed steps only: gh run view <id> --log-failed
- Full log for a job: gh run view <id> --log --job <job-id>
- Download artifacts: gh run download <id> -D .artifacts/<id>
4) Identify root cause (prefer the smallest fix)
- Use references/ci-failure-playbook.md for common patterns and safe fixes.
- Prefer: deterministic code/config fix > workflow plumbing fix > rerun flake.
5) Implement the fix (minimal diff)
- Update code/tests/config and/or .github/workflows/*.yml.
- Keep changes scoped to the failing job/step.
- If changing triggers/permissions/secrets, call out risk and get explicit confirmation.
6) Verify in GitHub Actions
- Rerun only failures: gh run rerun <id> --failed
- Rerun a specific job (note: job databaseId): gh run view <id> --json jobs --jq '.jobs[] | {name,databaseId,conclusion}'
- Watch until done: gh run watch <id> --compact --exit-status
- Manually trigger: gh workflow run <workflow> --ref <branch>
Safety notes
- Avoid
pull_request_target(and any change that runs untrusted fork code with secrets) unless the user explicitly requests it and understands the security tradeoffs. - Keep workflow
permissions:least-privilege; don’t broaden token access “just to make it pass”.
Deliverable (paste in chat / PR)
- Summary: ...
- Failing run: (job/step)
- Root cause: ...
- Fix: ...
- Verification: commands + new run link/id
- Notes/risks: ...