GitHub's Async Merge API: Your Merge Bot Is Now Legacy
Quick answer: GitHub's async merge API went generally available on 1 October 2026 and is now the recommended way to merge pull requests programmatically. GitHub's own documentation calls the synchronous merge endpoint "legacy" — with no deprecation date. The real migration cost is not the URL: the async API evaluates branch protection and repository rules when the merge runs, not when you submit it.
Almost every merge bot, release automation and "squash when green" script calls the same endpoint: PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge. On 1 October 2026 GitHub shipped a replacement and quietly reclassified that endpoint as the old way to do things.
Nothing broke. Nothing has a sunset date. That is exactly why this is worth ten minutes of your attention now instead of a surprise later.
What shipped on 1 October
The changelog entry describes an API that "processes merges asynchronously, helping your automations handle busy repositories without waiting for complex merges to finish in a single request." It can merge individual pull requests or stacks, add pull requests to merge queues, and — with the right permissions — optionally bypass rules.
Two sentences in that entry carry all the weight. It is "the recommended path for programmatically merging pull requests instead of the synchronous REST endpoint or GraphQL mutations." And it is "the only merge API that supports stacked pull requests."
The shape is submit-then-poll. GitHub's stacked pull requests reference puts it plainly: "the merge runs in the background when you submit a merge request and then you can poll for the result." On the REST reference for pull requests, three merge operations now sit next to each other — Merge a pull request, Merge a pull request asynchronously, and Get the result of an asynchronous merge. The third one is the new work.
This is GA, not preview. Status GA with no migration deadline is an unusual combination, and it tells you something about GitHub's intent: they want new automation on the async path, and they are not willing to break the old one yet.
"Legacy" is GitHub's word, not ours
Vendors are careful with that word, which is why it is notable. GitHub's stacked pull requests APIs and webhooks page states: "A stack cannot be merged with the legacy synchronous merge endpoints or mutations."
That sentence does two things. It restricts a capability to the new API, and it renames the old one. Note the plural and the "or mutations" — GraphQL merge mutations are in the same bucket. If your tooling standardised on GraphQL to cut round trips, that choice buys you nothing here.
What GitHub has not published is a deprecation notice, a sunset date, or a brownout schedule. Compare that with how the same company handles removals when it means them: workflow execution protections came with an enforcement date and an evaluate-mode window. The merge endpoint got a new adjective. Read that as years, not months — but also as the direction of travel, because capabilities are already being withheld from the old path.
The behaviour change that actually matters
Here is the line every bot author needs to read twice, from the same GitHub reference page: "Only the basic pull request state is checked when you submit an open PR. Branch protection and repository rules are evaluated later, when the merge actually runs."
That inverts the contract your automation was written against. With the synchronous endpoint, the response tells you whether the merge happened. A rules violation, a failing required check, a stale branch — all of it comes back in the same HTTP call that asked for the merge. Your error handling lives at the call site because that is where the error is.
With the async API, acceptance of the request means the request was well-formed and the pull request is in a plausible state. It does not mean the merge will succeed. The rules evaluation happens afterwards, out of band, and you find out by polling. A naive port — swap the path, keep the "if the call succeeded, we merged" logic — produces automation that reports success for merges that never landed. That is worse than a loud failure, because it is silent and it corrupts whatever you do next: tagging, changelog generation, deploy triggers.
If you have ever been bitten by a GitHub API whose response did not mean what you assumed — the same way the Actions run count started reporting "2,500+" — this is that failure mode, with worse consequences.
Sync versus async, side by side
| Synchronous merge endpoint | Async merge API | |
|---|---|---|
| GitHub's framing | "legacy synchronous merge endpoints" | "the recommended path", GA 1 Oct 2026 |
| When rules are evaluated | During the request | Later, when the merge runs |
| How you learn the outcome | The response | Poll for the result |
| Stacked pull requests | Not supported | Supported, and atomic across the stack |
| Merge queue | Not an advertised capability | Can add pull requests to merge queues |
| Behaviour under load | Request waits for a complex merge | Returns without waiting; work continues in background |
| Code you must write | One call, one branch of error handling | Submit, store the request id, poll with backoff, handle timeout |
The last row is the honest cost. "Poll with backoff and handle timeout" is an afternoon of real work, because you have to decide what your bot does when a merge request is accepted and simply has not resolved yet. Retry? Report pending and exit zero? Hold the CI job open? GitHub supplies no default answer.
Stacks are the forcing function
GitHub put stacked pull requests into public preview on 30 July 2026, installed via gh extension install github/gh-stack. A stack is an ordered series of pull requests, each a layer of a bigger change; merging the top ready layer lands it and every unmerged layer below it in one operation.
Atomicity is spelled out: "A stack merge request is atomic, meaning either the whole group of pull requests merges, or is added to the merge queue, or none of it is." That guarantee is the technical reason the old endpoint cannot serve stacks. A single-PR synchronous call has nowhere to put "all of these, or none."
So the practical trigger for migration is not the word "legacy". It is whether your org adopts stacks or merge queues. The moment one team does, any bot on the old path silently loses the ability to merge their work, and the failure will look like a permissions or state problem rather than an API-generation problem. Spec migrations usually announce themselves this way — see the MCP stateless migration for the same pattern in a different ecosystem.
Should you migrate now? An opinion
If your automation merges ordinary single pull requests on a repo with no merge queue and no stacks, do nothing this quarter. There is no deadline, the old endpoint works, and rewriting a working merge path to acquire a polling loop and a new class of pending state is a net increase in things that can go wrong.
If any of the following is true, do it now and do it properly. You maintain a merge bot other teams depend on. Your repo uses a merge queue. Anyone on your team has tried gh-stack. You are writing new merge automation from scratch. Your merge calls time out on a busy monorepo.
When you do migrate, treat the polling result — not the submission — as the merge event. Log the merge request id so a failed merge is traceable after the fact. And resist the urge to wrap the whole thing in a synchronous helper that blocks until resolution, which recreates the exact timeout problem the async API exists to solve. If you are converting existing calls by hand, a curl to fetch converter and a JSON formatter make reading the new response shapes less tedious than it sounds.
One more thing worth noticing: within days of the GA announcement, third-party repositories had open issues titled things like "teach agents the async merge API". Coding agents merge pull requests now, and they learn endpoints from documentation. An API GitHub labels "recommended" will spread through agent tooling faster than through hand-maintained scripts, so the async path may become the common one long before anyone deprecates the old one.
FAQ
Is the synchronous merge endpoint deprecated?
Not formally. GitHub's stacked pull requests documentation calls it "legacy" and the changelog recommends the async API instead, but no deprecation notice, sunset date or brownout schedule has been published. It continues to work.
What is the biggest difference for existing automation?
When failures surface. GitHub states that only basic pull request state is checked on submission, and that branch protection and repository rules are evaluated later when the merge runs. An accepted submission is not a completed merge, so your success condition has to move to the poll.
Can I merge a stacked pull request with the old endpoint or GraphQL?
No. GitHub states that a stack cannot be merged with the legacy synchronous merge endpoints or mutations. The async merge API is described as the only merge API that supports stacks.
Does the async API work with merge queues?
Yes — adding pull requests to merge queues is one of its stated capabilities, and a stack merge request can resolve to "added to the merge queue" rather than "merged" as its atomic outcome.
Can automation bypass branch protection with it?
The changelog says rules can optionally be bypassed with proper permissions. That is a capability gated on permissions, not a loophole — and it is worth auditing which of your tokens and apps hold the permission that enables it.
Where are the endpoints documented?
On GitHub's REST reference for pull requests, as two operations named "Merge a pull request asynchronously" and "Get the result of an asynchronous merge", listed alongside the original "Merge a pull request". The stacked pull requests reference covers the submit-and-poll behaviour and the atomicity guarantee.
Browse CI and automation tooling in the API and backend directory, or compare the wider field in developer tools.