GitHub Copilot PR Finisher

PR Finisher

Drive an open PR for the current branch to a merge-ready state from a GitHub Copilot cloud agent. Do not merge. When everything you can act on is done, report ready-for-human-merge and stop.

Execution context

This skill runs inside a GitHub Copilot cloud agent, not on a developer's machine.

• The agent's pushes do not trigger CI. Workflows on the PR will not re-run after the agent commits. Any existing statusCheckRollup reflects an earlier HEAD and goes stale the moment the agent pushes.
• Commit and push on every iteration that changes files. Changes that are not pushed are not available to the user.
• Local make targets are the agent's authoritative correctness signal before push. CI is observational only.
• Re-running CI is a hand-off to a human (close/reopen the PR, workflow_dispatch, or a push from a maintainer). The agent must surface this in its summary.
• No watch / no sleep loops. The agent has no async wait state; one pass + summary + stop.

Three merge-ready conditions

A PR is merge-ready when all three are satisfied. Work them concurrently.

Because the agent cannot re-trigger CI, "Checks" is satisfied at the agent's level when local validation passes and prior CI failures have been root-caused and fixed in the pushed commits. Final green CI requires a human to re-trigger after the agent stops.

Top-level PR comments and review bodies are useful feedback but not a merge gate. Read and action useful ones; do not block on them.

Hard rules

• Autopilot mode: Never ask for confirmation before taking action. Never prompt with "Should I proceed?", "Do you want me to…?", or any equivalent. Always act immediately and autonomously.
• Do not merge. Never run gh pr merge, enable auto-merge, or enqueue. This skill stops at "ready for merge."
• Do not post stand-alone PR comments. Only reply on existing review threads / comments that need a response. Do not ping reviewers or CODEOWNERS.
• Always disable pagers for gh: prefix with GH_PAGER="" or pipe through cat. Without this, commands hang in non-interactive shells.
• Read PR state once per pass and reuse it. Cache the initial gh pr view payload in a local snapshot file and use jq against that file until you perform an action that can change PR state (for example: push, update branch, resolve conflicts). Do not re-run overlapping gh pr view calls within the same unchanged turn sequence.
• Ignore platform-managed bot PRs by default. Stop without updating PRs authored by dependabot[bot], app/dependabot, renovate[bot], or another unrecognized bot unless the user explicitly asks to handle that bot. Continue for trusted GitHub automation such as app/github-copilot and github-actions[bot].
• Never wait for CI to re-run. No bash sleep, no gh run watch, no gh pr checks --watch, no re-check loop after push. The agent's pushes will not trigger workflows; waiting is futile.
• Local validation is non-negotiable before each push. Because CI will not re-run, the only correctness gate the agent gets is make ... locally. Treat a green local run as the bar.
• Commit and push every iteration that produces file changes. Unpushed changes are not visible to the user.
• Reviews are not done until reply + resolve both succeed. Code change alone ≠ thread handled.
• Smallest fix that works. Don't change unrelated code. Fix lint before tests.
• Pre-existing unrelated failures → identify explicitly in the summary; do not guess-fix.

CI-fix anti-patterns (do not do these)

A failing CI step is a signal, not a nuisance. Even though the agent cannot re-run CI to confirm, the following are forbidden and should trigger ask_user instead:

• Disabling, skipping, or neutering shared tooling (build caches, lint rules, type checks, env vars, required checks) to make a failure go away.
• "Temporary" disables with a TODO to re-enable later. They outlive the PR and become permanent.
• Lowering coverage thresholds, removing assertions, or loosening a test until it passes. If the test is wrong about product behavior, fix its logic (assertions, fixtures, setup); don't relax it.
• Bundling a workaround with a real fix ("belt and suspenders"). Ship one real fix or escalate. Never both.
• Special-casing one OS/runner to hide a failure on that platform.

Anti-pattern test: if the change would make the failure invisible on future PRs without solving it, stop and escalate.

Before declaring a tool broken on a platform: reproduce locally, check version/config, look for transient causes (timeouts, network, runner state). Most "X is broken on macOS/Windows" reports are transient flakes on healthy tooling.

For flaky infra (caches, registries, runners): prefer narrow fixes — targeted retry, higher timeout, pre-flight health check. If a narrow fix doesn't land in one or two attempts, escalate via ask_user.

Workflow

The agent runs this once. There is no monitoring loop.

1. Triage

mkdir -p /tmp/gh-aw/pr-finisher
PR_SNAPSHOT=/tmp/gh-aw/pr-finisher/pr-state.json
GH_PAGER="" gh pr view <number> --json author,state,isDraft,reviewDecision,mergeable,mergeStateStatus,statusCheckRollup,headRefOid,reviews,comments > "$PR_SNAPSHOT"
GH_PAGER="" gh api graphql --paginate --slurp \
  -f query='query($owner:String!,$repo:String!,$pr:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$pr){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved comments(first:100){pageInfo{hasNextPage} nodes{author{login} authorAssociation body createdAt url}}}}}}}' \
  -f owner=github -f repo=gh-aw -F pr=<number> \
  > /tmp/gh-aw/pr-finisher/review-threads.json
jq -s '.[0] + {reviewThreads: [.[1][] | .data.repository.pullRequest.reviewThreads.nodes[] | . + {comments: .comments.nodes, commentsPageInfo: .comments.pageInfo}]}' \
  "$PR_SNAPSHOT" /tmp/gh-aw/pr-finisher/review-threads.json \
  > "$PR_SNAPSHOT.tmp" && mv "$PR_SNAPSHOT.tmp" "$PR_SNAPSHOT"
GH_PAGER="" gh pr checks <number>

reviewThreads is not a supported gh pr view --json field. The GraphQL data above is flattened into the snapshot shape used by copilot-review. If a thread's commentsPageInfo.hasNextPage is true, fetch its remaining comments before judging whether it is addressed. Do not treat truncated or failed reads as resolved feedback.

If merged/closed, report and stop. Also stop if the author is a platform-managed dependency bot or another unrecognized bot, unless the user explicitly requested handling that bot-authored PR. This author gate is independent of reviewer eligibility. Otherwise classify each condition as ✅ / ❌ / ⏳ / ❓ using the snapshot file plus gh pr checks. The CI snapshot here is your only view of CI for this run — capture which checks failed and why before changing anything, because after you push it will be stale.

2. Address Reviews

2a. Resolve Copilot-answered threads

Before delegating to copilot-review, find review threads where Copilot has already replied with a substantive answer but the thread has not yet been marked as resolved. Resolve those threads immediately — no code changes are needed for them.

# Identify unresolved threads that already have a Copilot reply
jq '.reviewThreads[]? | select(.isResolved==false) | select(any(.comments[]?; .author.login == "app/github-copilot" or (.author.login | test("copilot"; "i"))))' "$PR_SNAPSHOT"

For each such thread:

• Confirm the Copilot reply is substantive and actually addresses the concern (not merely an acknowledgment or partial response).
• If the reply fully addresses the concern, resolve the thread.
• If the reply is incomplete or the concern is not satisfied, treat the thread as still open and address it in step 2b below.