gh-fix-ci — Fix Failing GitHub PR Checks
Overview
Use gh to locate failing PR checks, fetch GitHub Actions logs for actionable failures, summarize the failure, then implement when the user has asked for a fix. If the user only asked what failed, stop after the summary. If a plan-oriented skill (e.g. create-plan) is available and the fix is broad or risky, use it; otherwise keep the plan inline.
Scope: GitHub Actions only. For external providers (Buildkite, CircleCI, etc.), report the link URL and stop — don't attempt to inspect them.
Prereq: authenticate the GitHub CLI once (gh auth login), confirm with gh auth status. Typically needs repo + workflow scopes.
Inputs
Operates on the current branch's PR by default. Accepts an explicit PR number or URL if provided.
Workflow
Verify gh auth. gh auth status. If unauthenticated, ask the user to run gh auth login before proceeding.
Resolve the PR. Prefer the current branch: gh pr view --json number,url. Otherwise use the provided number/URL.
List failing checks.
gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow- If a field is rejected (gh field drift), retry with the available fields gh reports, or fall back to bare
gh pr checks <pr>.
- Filter for
state == "failure" or bucket == "fail".
For each failing GitHub Actions check, fetch logs.
- Extract the run id from
link (e.g. .../actions/runs/<run_id>/...).
gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headShagh run view <run_id> --log (full log)- If the log indicates the run is still in progress or a job log is needed directly:
- Get failing job ids:
gh run view <run_id> --json jobs -q '.jobs[] | select(.conclusion=="failure") | .databaseId'
- Then:
gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs" > <path>
Scope non-Actions checks. If link is not a GitHub Actions URL, label external and report only the URL.
Summarize for the user. Failing check name, run URL, concise log snippet, and explicit callouts for missing logs.
Plan. Use create-plan if available for broad or risky fixes; otherwise inline a concise plan. Continue directly when the user has asked to fix CI. Pause only when the intended change is destructive, ambiguous, outside the repo, or materially broader than the CI failure.
Implement. Apply the plan, summarize diffs/tests, and ask about opening a follow-up commit/PR only if the user has not already requested that workflow.
Recheck. Suggest re-running local tests and gh pr checks <pr> to confirm green.
1---2name: gh-fix-ci3description: Use when a user asks to debug or fix failing GitHub PR checks / GitHub Actions runs (e.g., 'CI is red', 'why is this PR failing', 'fix the failing checks', 'PR checks broken'). Inspects checks via gh, summarizes failure context, and implements when the user has asked for a fix.4---56# gh-fix-ci — Fix Failing GitHub PR Checks78## Overview910Use `gh` to locate failing PR checks, fetch GitHub Actions logs for actionable failures, summarize the failure, then implement when the user has asked for a fix. If the user only asked what failed, stop after the summary. If a plan-oriented skill (e.g. `create-plan`) is available and the fix is broad or risky, use it; otherwise keep the plan inline.1112**Scope:** GitHub Actions only. For external providers (Buildkite, CircleCI, etc.), report the `link` URL and stop — don't attempt to inspect them.1314**Prereq:** authenticate the GitHub CLI once (`gh auth login`), confirm with `gh auth status`. Typically needs `repo` + `workflow` scopes.1516## Inputs1718Operates on the current branch's PR by default. Accepts an explicit PR number or URL if provided.1920## Workflow21221. **Verify gh auth.** `gh auth status`. If unauthenticated, ask the user to run `gh auth login` before proceeding.23242. **Resolve the PR.** Prefer the current branch: `gh pr view --json number,url`. Otherwise use the provided number/URL.25263. **List failing checks.**27 - `gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow`28 - If a field is rejected (gh field drift), retry with the available fields gh reports, or fall back to bare `gh pr checks <pr>`.29 - Filter for `state == "failure"` or `bucket == "fail"`.30314. **For each failing GitHub Actions check, fetch logs.**32 - Extract the run id from `link` (e.g. `.../actions/runs/<run_id>/...`).33 - `gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha`34 - `gh run view <run_id> --log` (full log)35 - If the log indicates the run is still in progress or a job log is needed directly:36 - Get failing job ids: `gh run view <run_id> --json jobs -q '.jobs[] | select(.conclusion=="failure") | .databaseId'`37 - Then: `gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs" > <path>`38395. **Scope non-Actions checks.** If `link` is not a GitHub Actions URL, label external and report only the URL.40416. **Summarize for the user.** Failing check name, run URL, concise log snippet, and explicit callouts for missing logs.42437. **Plan.** Use `create-plan` if available for broad or risky fixes; otherwise inline a concise plan. Continue directly when the user has asked to fix CI. Pause only when the intended change is destructive, ambiguous, outside the repo, or materially broader than the CI failure.44458. **Implement.** Apply the plan, summarize diffs/tests, and ask about opening a follow-up commit/PR only if the user has not already requested that workflow.46479. **Recheck.** Suggest re-running local tests and `gh pr checks <pr>` to confirm green.
jmagar