iterate-pr

Iterate on PR Until CI Passes

Continuously iterate on the current branch until all CI checks pass and review feedback is addressed.

Requires: GitHub CLI (gh) authenticated and available.

Process

Step 1: Identify the PR

gh pr view --json number,url,headRefName,baseRefName

If no PR exists for the current branch, stop and inform the user.

Step 2: Check CI Status First

Always check CI/GitHub Actions status before looking at review feedback:

gh pr checks --json name,state,bucket,link,workflow

The bucket field categorizes state into: pass, fail, pending, skipping, or cancel.

Important: If any of these checks are still pending, wait before proceeding:

• Linting checks (ruff, black, flake8, mypy, pylint)
• Test runners (pytest, unittest)
• Coverage checks (codecov, coveralls)
• Any code analysis checks

These tools may post additional feedback comments once their checks complete. Waiting avoids duplicate work.

Step 3: Gather Review Feedback

Once CI checks have completed (or at least the bot-related checks), gather human and bot feedback:

Review Comments and Status:

gh pr view --json reviews,comments,reviewDecision

Inline Code Review Comments:

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments

PR Conversation Comments (includes bot comments):

gh api repos/{owner}/{repo}/issues/{pr_number}/comments

Look for bot comments from: Codecov, Dependabot, and other automated tools.

Step 4: Investigate Failures

For each CI failure, get the actual logs:

# List recent runs for this branch
gh run list --branch $(git branch --show-current) --limit 5 --json databaseId,name,status,conclusion

# View failed logs for a specific run
gh run view <run-id> --log-failed

Do NOT assume what failed based on the check name alone. Always read the actual logs.

Step 5: Validate Feedback

For each piece of feedback (CI failure or review comment):

1. Read the relevant code - Understand the context before making changes
2. Verify the issue is real - Not all feedback is correct; reviewers and bots can be wrong
3. Check if already addressed - The issue may have been fixed in a subsequent commit
4. Skip invalid feedback - If the concern is not legitimate, move on

Step 6: Address Valid Issues

Make minimal, targeted code changes. Only fix what is actually broken.

Step 7: Commit and Push

git add -A
git commit -m "fix: <descriptive message of what was fixed>"
git push origin $(git branch --show-current)

Step 8: Wait for CI

Use the built-in watch functionality:

gh pr checks --watch --interval 30

This waits until all checks complete. Exit code 0 means all passed, exit code 1 means failures.

Alternatively, poll manually if you need more control:

gh pr checks --json name,state,bucket | jq '.[] | select(.bucket != "pass")'

Step 9: Repeat

Return to Step 2 if:

• Any CI checks failed
• New review feedback appeared

Continue until all checks pass and no unaddressed feedback remains.

Exit Conditions

Success:

• All CI checks are green (bucket: pass)
• No unaddressed human review feedback

Ask for Help:

• Same failure persists after 3 attempts (likely a flaky test or deeper issue)
• Review feedback requires clarification or decision from the user
• CI failure is unrelated to branch changes (infrastructure issue)

Stop Immediately:

• No PR exists for the current branch
• Branch is out of sync and needs rebase (inform user)

Tips

• Use gh pr checks --required to focus only on required checks
• Use gh run view <run-id> --verbose to see all job steps, not just failures
• If a check is from an external service, the link field in checks JSON provides the URL to investigate