ci-fix
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.
When & Why to Use This Skill
This Claude skill automates the troubleshooting and resolution of GitHub Actions CI failures. By leveraging the GitHub CLI (gh), it enables agents to programmatically inspect failing logs, identify root causes, apply code or workflow patches, and verify fixes through targeted reruns, significantly reducing the time to restore green builds.
Use Cases
- 1. Automated CI Failure Diagnosis: Rapidly analyze verbose logs and failed steps from GitHub Actions to pinpoint the exact cause of build breaks without manual log diving.
- 2. Workflow Configuration Repair: Detect and fix misconfigurations in .github/workflows files, such as incorrect environment variables, permission issues, or deprecated action versions.
- 3. Flaky Test Management: Identify non-deterministic failures and use targeted reruns for specific failed jobs to confirm stability and reduce developer friction.
- 4. Rapid Patch Verification: Automatically implement minimal code fixes and trigger 'gh run rerun --failed' to verify the solution in the actual CI environment.
| 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)
- Confirm
ghcontext- Auth:
gh auth status - Repo:
gh repo view --json nameWithOwner -q .nameWithOwner - If needed, add
-R OWNER/REPOto all commands. - If
ghis not installed or not authenticated, tell the user and ask whether to install/authenticate or proceed by pasting logs/run URLs manually.
- Auth:
- 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
- Recent failures:
- Open in browser:
gh run view <id> --web
- If you have a run URL, extract the run ID:
- 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>
- Job/step overview:
- Identify root cause (prefer the smallest fix)
- Use
references/ci-failure-playbook.mdfor common patterns and safe fixes. - Prefer: deterministic code/config fix > workflow plumbing fix > rerun flake.
- Use
- 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.
- Update code/tests/config and/or
- 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>
- Rerun only failures:
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: <link/id> (job/step)
- Root cause: ...
- Fix: ...
- Verification: commands + new run link/id
- Notes/risks: ...