GitHub · Pull requests · Merge queue · Checked October 26, 2026

GitHub: the branch merges through a merge queue

Repository administrators can require a merge queue on a branch: "Require merge queue" in a branch protection rule, or the merge_queue rule of a ruleset ("Merges must be performed via a merge queue"). A pull request into that branch is then not merged directly. Once it has passed all required branch protection checks, a user with write access to the repository adds it to the queue; the queue makes sure its changes pass all required status checks when applied to the latest version of the target branch and any pull requests already in the queue, and GitHub then merges it with the merge method set for the queue (GitHub's managing a merge queue and merging a pull request with a merge queue). GraphQL's isMergeQueueEnabled says whether the pull request's base branch has a merge queue, and mergeQueueEntry where the pull request is in it (checked October 26, 2026).

POST /graphql   pullRequest(number: N) { isMergeQueueEnabled isInMergeQueue mergeQueueEntry { position state } }
POST /graphql   enqueuePullRequest(input: { pullRequestId: ID, expectedHeadOid: SHA }) { mergeQueueEntry { position } }
PUT  /repos/OWNER/REPO/pulls/N/merge-async   { "merge_action": "merge_queue", "sha": SHA }

Why it is not merged directly

REST's merge endpoint: "Merge a pull request" (PUT /repos/OWNER/REPO/pulls/N/merge) does not support merging with a merge queue; GitHub recommends the asynchronous merge API instead (GitHub's REST API endpoints for pull requests).
The asynchronous merge: PUT …/merge-async merges in the background or adds the pull request to a merge queue. Its merge_action default uses a merge queue if one is configured for the target branch, merge_queue adds to the queue, direct_merge merges without it. A 202 means the request was accepted and runs in the background; a 200 comes back at once if the pull request is already merged or already in a merge queue, and "enqueued" means added to the queue, not merged; a 400 means it cannot be merged (closed, still a draft), as only basic pull request state checks run at that stage, not branch protection rules or repository rules; a 409 means another merge request is already pending for it. The commit title, message and merge_method apply to direct merges only.
GraphQL: enqueuePullRequest adds the pull request only if it can be added immediately; if it cannot, the mutation returns an error that explains why. expectedHeadOid is the head it expects, and jump adds it to the front of the queue. dequeuePullRequest removes it.
On GitHub: "Merge when ready" adds the pull request to the queue. Clicked before all requirements pass, it enables auto-merge and adds the pull request when they are met, even if "Allow auto-merge" is disabled for the repository. An administrator may merge directly with "Merge without waiting for requirements to be met (bypass branch protections)", if the branch protection settings allow it.

What the queue does with it

A merge group: the queue groups the pull request's changes with the latest version of the base branch and the pull requests ahead of it, on a temporary branch with a special prefix, dispatches a merge_group event of type checks_requested, and merges once the checks the base branch requires pass. Pull requests are merged first in, first out.
Your checks must run on the merge group: a GitHub Actions workflow that reports a required check needs the merge_group event as a trigger, separate from pull_request and push; without it the check is not reported and the merge fails (see a required check stuck at "Expected"). Another CI service must run on pushes to branches beginning with gh-readonly-queue/{base_branch}, whose SHA differs from the pull request's.
The settings: the merge method; build concurrency (1 to 100 merge_group webhooks at once); whether only non-failing pull requests merge (a ruleset's grouping_strategy: ALLGREEN, every pull request's merge commit in the group must pass, or HEADGREEN, only the head of the group); the status check timeout, after which checks that have not reported count as failed; and the minimum and maximum group size with a wait time. A branch protection rule with * in its branch name pattern cannot enable a merge queue.
Where it stands: GraphQL gives the entry's position, state (QUEUED, AWAITING_CHECKS, MERGEABLE, UNMERGEABLE, LOCKED) and estimatedTimeToMerge. On GitHub, the Branches page and the merge queue link at the bottom of the pull request's timeline show the queue. Jumping to the top makes every pull request in progress build again.

Why it left the queue

The reasons GitHub lists: the CI service reported test failures for a merge group; the queue timed out awaiting a successful CI result; a user removed it through the API or the merge queue interface; a branch protection failure could not be resolved automatically; or, grouped with the latest target branch and the changes ahead of it, it had failed required status checks or conflicts with the base branch.
The timeline says why: the pull request's timeline shows the reason it was removed. The pull requests behind it are grouped again without its changes.

What to do

Add it to the queue: use Merge when ready on GitHub, enqueuePullRequest, or merge-async with merge_action merge_queue, rather than the direct merge endpoint.
Pass the branch's rules first: the pull request must meet them before it can join: approving reviews (see a code owner's review), resolved conversations (see the merge waits for conversations), signed commits (see unsigned commits), required checks.
Make the checks run on the merge group: add merge_group to the workflows that report required checks, or run your CI on gh-readonly-queue/ branches.
After a removal: read the reason in the timeline, fix it, and add the pull request again.

GitHub pull requests in IntelliJ IDEA

Pull Request Inbox for GitHub, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, shows a pull request's reviews, checks and conversations next to the diff, and merges it with the methods the target branch allows. When GitHub calls the pull request blocked, its merge checks name what they can read: required checks that have not reported, a review still required, unresolved conversations and unsigned commits the rules hold against it. When the target branch merges through a merge queue, its Merge adds the pull request to the queue (GraphQL's enqueuePullRequest), and the merge checks say that the branch merges through a queue, or where the pull request is in it and whether it is waiting for checks, can be merged or cannot. The review inbox, diffs and conversations are free; approving, commenting, resolving and merging are Pro (US$1.50 a month, with a 30-day trial).

GitHub is a trademark of GitHub, Inc.; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by GitHub, Inc. or JetBrains.