merge-queue

name	merge-queue
description	Use when you need to add a PR to a GitHub merge queue, check what's currently queued, or find out why a PR was removed from the queue. The gh CLI has no built-in merge-queue commands, so this skill provides scripts that use the GraphQL API.
allowed-tools	Bash(bash skills/merge-queue/scripts/*:*)

Merge Queue

Enqueue a PR

Run bash skills/merge-queue/scripts/enqueue-pr.sh [PR_NUMBER_OR_URL] to enqueue a PR. Omit the argument to enqueue the current branch's PR.

If the PR is not yet eligible (checks pending, missing approvals), use await-and-enqueue.sh instead — see below.

Accepted input formats

• PR number: 652 (uses the current repo context from gh)
• PR URL: https://github.com/owner/repo/pull/652
• Omitted: uses the current branch's PR

The owner/repo#number format is not supported — use a URL or number instead.

Check queue status

Run bash skills/merge-queue/scripts/queue-status.sh [OWNER/REPO] [BRANCH] to list PRs currently in the merge queue.

Both arguments are optional — defaults to the current repo and main branch.

Shows each entry's position, state, PR title/URL, author, enqueuer, and estimated time to merge.

Investigate dequeue reasons

Run bash skills/merge-queue/scripts/dequeue-reason.sh <PR_NUMBER_OR_URL> to find out why a PR was removed from the merge queue.

Shows each removal event's timestamp, reason (e.g. failed_checks, merge_conflict), and the commit SHA at the time of removal.

Await and enqueue

Run bash skills/merge-queue/scripts/await-and-enqueue.sh [PR_NUMBER_OR_URL] to poll a PR until all required checks pass and the PR is approved, then automatically enqueue it. Exits early if any check fails.

Use this when enqueue-pr.sh rejects a PR because checks are still pending. GitHub's auto-merge API (gh pr merge --auto) does not work with merge queues, so this script fills that gap.

Set POLL_INTERVAL (default: 30 seconds) to control how often it checks.

Prerequisites

• gh CLI authenticated with write access to the target repository
• jq installed
• The target repository must have merge queues enabled in its branch protection rules

Constraints

• Rulesets only: await-and-enqueue.sh discovers required checks from repository rulesets only. Repositories using classic branch protection rules will not have their required checks verified before enqueuing.

Common errors

• "Pull request is already in the merge queue" — the PR was previously enqueued; no action needed.
• "Pull request is not mergeable" — the PR may need approvals, passing checks, or conflict resolution before it can be enqueued.
• "Resource not accessible by integration" — the gh token lacks sufficient permissions.
• "status checks are expected" — required checks haven't finished yet. Use await-and-enqueue.sh to poll and enqueue once they pass.
• gh pr merge --auto fails with merge queues — GitHub's auto-merge API does not support merge queues. Use await-and-enqueue.sh instead.