GitHub Async Pull Request Merge API: Update Bots for Stacked PRs and Merge Queues

If you maintain merge bots, release scripts or GitHub Actions workflows that land pull requests, you need to update them.

What GitHub actually shipped​

GitHub's changelog says the API can merge single or stacked pull requests, add pull requests to a merge queue, or merge them directly. Users who have permission can also choose to bypass repository rules. Because the work happens in the background, automation in busy repositories no longer has to wait for a complex merge to finish within one request.

The pattern has two steps:

1. Submit the merge with a PUT request.
2. Poll with a GET request using the request ID that came back, until you have a final result.

GitHub's REST documentation describes the endpoint as one that "merges a pull request into the base branch in the background or adds it to a merge queue." GitHub says background processing allows certain types of errors to be retried and reduces the risk of timeouts for complex merges. The docs also call it the required API for merging stacked pull requests. For a stacked pull request, the operation includes all open downstack pull requests. When GitHub accepts a new request, it returns a 202 response with a UUID, and you use that UUID to look up the result.

Section summary: This is one merge API for direct merges, merge-queue submissions and stacks. In exchange, your code has to wait for the answer instead of getting it immediately.

The old endpoint isn't gone, but it's now second choice​

The synchronous PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge endpoint is still in the docs. It now opens with a warning: "We recommend using the asynchronous merge API instead. This endpoint does not support stacked pull requests or merging with a merge queue." It still accepts commit_title, commit_message, a sha that the pull request head must match to allow merge, and a merge_method that can be one of merge, squash, or rebase. Existing scripts that merge ordinary pull requests directly won't break today.

They will break once stacks are involved. Intel's torch-xpu-ops project ran into this in September 2026. A pull request filed there on September 22 explains that the project's merge bot called the synchronous endpoint, and GitHub refused the call with: "Merging stacked PRs via this endpoint is not supported. Use the asynchronous merge endpoint instead." There was no workaround on the pull request side, because GitHub rejects retargeting a stacked PR's base with "Cannot change the base branch because the pull request is part of a stack".

The project's fix was simple. The asynchronous endpoint is the documented path for stacks and handles ordinary pull requests too, so this uses it unconditionally instead of branching on whether a stack is involved. That approach makes sense for most teams. Supporting two merge code paths just to save one polling loop is rarely worth it.

Section summary: Synchronous merges still work for simple cases. Merge queues and stacks need the async API, and GitHub has said which path it wants you on.

The trap: "accepted" does not mean "merged"​

This is the part most likely to cause bugs. Old merge scripts often treat a 2xx response as proof that the code landed. With the async API, a 202 only means GitHub accepted the request. It does not confirm the merge happened.

The Intel bot shows the right way to handle it. Its author noted that the endpoint enqueues and reports back by uuid, and branch protection is only evaluated once the request runs, so the outcome is read from the poll rather than from the call. In that design:

• A pending request is followed for up to five minutes.
• An enqueued result is reported as enqueued, not merged, because the merge queue decides when the pull request actually lands.
• A 409 response, meaning a request already exists for that pull request, is followed through its existing UUID instead of starting a second request.

The bot's testing shows why this matters. With a token that lacked push access, the submit step returned status: pending with a uuid and the poll then returned status: failed with the branch-protection message. The submit call looked fine, and the poll showed the failure. A script that stopped after the PUT would have reported success for a merge that never happened.

Here's a practical checklist for porting your automation:

1. Treat 202 as "in progress." Store the UUID and poll it.
2. Handle all outcomes: pending, merged, enqueued and failed. For a merge queue, "enqueued" is the final answer to your request, not a confirmed merge.
3. Expect branch protection failures in the poll. The submit step does not run your rules.
4. Handle 409 without failing. Pick up the existing request instead of firing a new one.
5. Pin the head SHA if your bot must merge only the exact commit it reviewed. The synchronous API has long offered a SHA-match guard for this.
6. Use the rule-bypass option carefully. GitHub only lets you bypass rules if you have permission to do so. The API gives your bot no extra authority, so keep bot tokens scoped tightly.

Section summary: Build a small state machine instead of a one-shot merge call. Your on-call engineers will thank you.

Why stacked pull requests forced this change​

Stacked pull requests are GitHub's built-in support for chains of dependent changes, and they explain why a synchronous call no longer fits. GitHub's documentation, which still labels stacks as in public preview and subject to change, sets these rules:

• Stacked pull requests merge from the bottom (closest to the trunk) up.
• You cannot merge a mid-stack pull request in isolation, the pull requests below it will always merge with it.
• Before a pull request in a stack can merge, all pull requests below it must be approved with passing checks, the stack must have a linear history, and the current pull request must meet all branch protection requirements for the stack base, such as main.
• Auto-merge is not supported for stacked pull requests.

When the merge goes through, the selected pull request and all unmerged pull requests below it land on the base branch together as a single operation, ordered from the bottom up in the resulting history. Checking and landing several pull requests as one operation can take a while, so a blocking HTTP call that might time out is a poor fit. A background job you can poll fits much better.

The docs say it plainly: if you merge via the API and want to use stacked pull requests, you'll need use the asynchronous merge API for stacks.

What it means for GraphQL users​

Teams that merge through GraphQL should take note too. GitHub's merge queue API support started there. When merge queue was in public beta in 2023, GitHub told developers to call the enqueuePullRequest mutation to add a pull request to the queue or dequeuePullRequest to remove a pull request. The new changelog now names the async REST API as the preferred path over GraphQL mutations for merging from code.

GitHub has not announced that any mutation is deprecated or will be removed. Even so, when a vendor publicly names a "recommended path," it is usually a good idea to plan the migration before you have to.

Analysis: a sensible change with a learning curve​

From an engineering point of view, the change is reasonable. Merge queues, multi-PR stacks and ruleset evaluation are long-running jobs, and pretending they can finish within one HTTP request was always going to fail at scale. Asynchronous submit-and-poll is the standard pattern for this kind of work on almost every major cloud platform.

There is a cost. Every merge bot needs polling logic, timeout handling and some way of telling "queued" apart from "landed." Small teams with simple workflows may find this annoying. Those teams can keep using the synchronous endpoint for now. For organizations already using merge queues, or planning to try stacks, the migration is required. Intel's experience shows it can be a small, contained change if it's designed well.

The bottom line: If your automation merges pull requests, check whether it uses the synchronous endpoint or GraphQL mutations, and port it to the async API before stacks show up in your repositories. Most important of all, never let a 202 response count as a successful merge.