pr-fix-ci

PR Fix CI

Iteratively fix failed GitHub Actions checks on a pull request until all CI jobs pass. This goes beyond mechanical fixes — it evaluates whether failing tests are actually useful and proposes restructuring or removal when tests are brittle, test phantom behavior, or don't meaningfully contribute to code quality.

Inputs

The user provides one of:

• A GitHub PR URL (e.g. https://github.com/owner/repo/pulls/13)
• A PR number with the repo context already established
• "this PR" when the current branch already has an open PR

Extract the owner, repo, and PR number from whichever form is given.

Workflow

Repeat the following cycle until all CI checks pass.

1. Gather context

Fetch in parallel:

• PR metadata:

  gh pr view <N> --json title,body,headRefName,baseRefName,state --repo <owner>/<repo>
  

• All check statuses:

  gh pr checks <N> --repo <owner>/<repo>
  

Note: gh pr checks exits with code 1 when any check fails — this is expected, not an error.

2. Identify actionable failures

Not all failing checks are fixable. Separate them:

• Actionable — GitHub Actions jobs you can fix (test, build, lint, type check, etc.). These show as links to github.com/.../actions/runs/....
• Not actionable — Third-party checks (Netlify deploy previews, Vercel, external services, Copilot review). These have different URL patterns (e.g. app.netlify.com, vercel.com). Skip these entirely.

If no actionable failures exist (only external checks failing), report this to the user and stop.

3. Rebase onto the base branch

Before analyzing failures, make sure the PR branch is up to date with its base branch. Many CI failures are pre-existing issues that have already been fixed on the base branch — rebasing picks up those fixes for free and avoids duplicating work.

git fetch origin <baseRefName>
git checkout <headRefName>
git rebase origin/<baseRefName>
git push origin <headRefName> --force-with-lease

If the rebase has conflicts, resolve them. After pushing, a new CI run will start. Wait for it to complete (step 9), then re-evaluate. If CI is now green, you're done. If failures remain, continue to step 4.

4. Get failure logs

For each failed GitHub Actions job:

1. Extract the run ID and job ID from the check URL.
2. Identify which step failed:

   gh run view <run_id> --repo <owner>/<repo> --json jobs \
     --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion, steps: [.steps[] | select(.conclusion == "failure") | {name, conclusion}]}'
   

3. Fetch the job logs:

   gh api repos/<owner>/<repo>/actions/jobs/<job_id>/logs
   

4. Focus on the last 80-100 lines of output — that's where the error details and stack traces live. Parse out the actual failures: test names, assertion errors, build errors, lint violations, etc.

5. Triage each failure

This is the most important step. For each failure, read the failing code and its test/source context, then decide:

Fix — the code or test has a real bug

• Build errors, import mistakes, missing dependencies
• Tests that correctly catch regressions introduced by the PR
• Lint violations in files the PR modified

Restructure — the test is broken in a way that reveals bad test design

Look for these red flags:

• Hardcoded counts (e.g. expect(routes).toHaveLength(11)) that break every time a new item is added. The count doesn't test behavior — it tests that nothing changed. Replace with assertions on specific items.
• Testing implementation details (e.g. reading raw source code to check for a specific import). If the import is renamed or the pattern changes, the test breaks with zero functional impact.
• Testing phantom behavior — the test assumes a component works a certain way, but the component was never built that way. The test was written for a spec, not for reality.
• Stale test data — the test hardcodes a value that has since changed in the source of truth (e.g. a social media handle typo, a URL that was updated).
• Missing test infrastructure — the test fails because it's missing mocks (e.g. IntersectionObserver, matchMedia, ResizeObserver) that other test files in the project already set up. Copy the established mocking pattern.

Remove — the test provides no value

• Tests that read source code as strings and check for keywords
• Tests that only verify "nothing changed" without testing behavior
• Tests for component structures that never existed

Ask the user — you're unsure

When you think a test should be restructured or removed but aren't certain, use AskUserQuestion to check. Frame it concisely:

"The test it('shows only enabled service pages') assumes ServicesOverview reads from the route config, but the component uses hardcoded data. This test can never pass as written. Should I remove it, or rewrite it to test what the component actually does?"

Bias toward asking when:

• Deleting a test entirely (vs restructuring it)
• The test has a ticket reference (e.g. HOME-04) suggesting someone specifically wanted this coverage
• You're not sure if the behavior it's testing matters

6. Apply fixes

Edit files directly. Prefer Edit for surgical changes, Write only for full rewrites. When restructuring tests:

• Keep assertions that test real behavior (e.g. toContain for specific items) and remove assertions that test quantity (e.g. toHaveLength)
• Update test names to match what they actually verify
• Copy mock patterns from other test files in the project rather than inventing new ones

7. Verify locally

Run the full test suite, not just the previously-failing files. A fix in one file can break another.

# Run all tests
npm test  # or npx vitest run, npx jest, etc.

# Build
npm run build

# Lint changed files (to avoid noise from unrelated files)
npx eslint <changed-files>

Discover the right commands from package.json scripts, the CI workflow file (.github/workflows/*.yml), or the project's CLAUDE.md. Don't assume a specific test runner.

If verification fails, fix the new failure before proceeding.

8. Commit and push

Stage only the files you changed. Write a descriptive commit message that explains what was fixed and why, not just "fix tests".

git add <specific-files>
git commit -m "<message>"
git push origin <branch>

If the push is rejected because the remote has new commits, pull with rebase first:

git stash  # if dirty working tree
git pull --rebase origin <branch>
# resolve any conflicts
git stash pop
git push origin <branch>

9. Wait for CI

Poll until the new CI run completes:

# Find the latest run on this branch
gh run list --repo <owner>/<repo> --branch <branch> --limit 1 \
  --json databaseId,status,conclusion

# Once you have the run ID, check its status
gh run view <run_id> --repo <owner>/<repo> \
  --json status,conclusion,jobs \
  --jq '{status, conclusion, jobs: [.jobs[] | {name, status, conclusion}]}'

Wait 60 seconds between polls. CI typically takes 1-3 minutes for most projects.

10. Evaluate result

Once CI completes:

• All checks pass → report success and stop.
• Same failures persist → something was missed. Go back to step 4.
• New failures appeared → the fix broke something else. Go back to step 4.

Also re-check the full PR checks (step 2) since external checks may have updated too.

11. Completion

When all actionable CI checks are green, report:

• Total rounds completed
• What was fixed, restructured, or removed (and why)
• Any pre-existing failures that remain (not introduced by this PR)
• Final check status

Tips

• Fetch PR metadata and checks in parallel to save time.
• Read the CI workflow file (.github/workflows/*.yml) early to understand what commands CI runs — they may differ from local dev commands.
• When the same mock is missing across multiple test files, check if the project has a test setup file (e.g. vitest.config.js setup files, jest.setup.js) and fix it there instead of per-file.
• If a test restructure touches many files, do all edits first, verify once, then commit once — don't commit per-file.
• When fixing hardcoded counts, grep the test directory for similar patterns (toHaveLength, toBe(N) where N is a count) and fix them proactively to avoid another round.