--- 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 `gh` to 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\/`. - Otherwise: - Recent failures: `gh run list --limit 20 --status failure` - Branch failures: `gh run list --branch --limit 20 --status failure` - Workflow failures: `gh run list -w --limit 20 --status failure` - Open in browser: `gh run view --web` 3) Pull the signal from logs - Job\/step overview: `gh run view --verbose` - Failed steps only: `gh run view --log-failed` - Full log for a job: `gh run view --log --job ` - Download artifacts: `gh run download -D .artifacts\/` 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 --failed` - Rerun a specific job (note: job **databaseId**): `gh run view --json jobs --jq '.jobs[] | {name,databaseId,conclusion}'` - Watch until done: `gh run watch --compact --exit-status` - Manually trigger: `gh workflow run --ref ` ## 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:** ...