| name | merge-pr |
| description | Merge a pull request into main, monitoring the merge queue, retrying CI flakes, and re-enqueuing if necessary |
When the user asks to merge a pull request (e.g., "merge PR ", "merge this PR", or monitor its merge):
- Enqueue for Merge: Run
gh pr merge <pr_number> --auto --squash to enable auto-merge or add the pull request to the merge queue.
- Force / Admin Merge: CRITICAL: Passing
--admin to bypass the
merge queue or required checks requires explicit user permission or
consent. Only pass --admin (e.g., gh pr merge <pr_number> --admin --squash) if the user has explicitly requested or approved a force/admin
merge. Never invoke --admin autonomously.
- Invoke a Background Shepherd: Launch a background subagent with the role
Merge PR Shepherd to continuously watch the PR until it merges.
- Leverage Existing CI Skills:
- Have the subagent use the
monitor-ci-results skill to watch for CI
check failures and generate analysis reports.
- Have the subagent use the
buildkite-retry-job skill
(retry_buildkite_jobs.py <pr_number>) to automatically retry any
transient network flakes (e.g., HTTP 504 gateway timeouts, downloader
errors).
- Soft-Failing Jobs: Experimental Buildkite jobs (e.g.
*rolling*
Bazel) are non-blocking soft failures; do not treat them as merge blockers.
- When the PR is queued, actively discover the merge queue branch via
gh api repos/:owner/:repo/branches --jq '.[].name | select(test("gh-readonly-queue/.*/pr-<pr_number>-"))'
and monitor commit statuses/Buildkite builds running on that temporary
branch.
- Queue Shepherding: Periodically check
gh pr view <pr_number> --json state,autoMergeRequest,mergeStateStatus,mergeable. While state is
"OPEN", ensure auto-merge is enabled / queued by running gh pr merge <pr_number> --auto --squash. If autoMergeRequest is null (e.g., ejected
from the merge queue due to a CI flake in the temporary queue branch),
re-enqueue it for merge by running gh pr merge <pr_number> --auto --squash
once checks are retried or green.
- Completion Notification: Once
state becomes "MERGED", send a high-priority message back to the parent conversation.
