GitHub’s asynchronous merge API became generally available on October 1, 2026. The API gives developers and platform teams a background-oriented way to merge individual pull requests, submit pull requests to merge queues, and merge stacked pull requests.
The change matters most for delivery automation. Instead of depending on a synchronous merge request or GraphQL mutation to complete the operation within one request, clients submit an asynchronous merge request and then check its status with a returned request ID. GitHub identifies this API as the recommended programmatic merge path for new and existing automation.
What changed
The generally available API supports several merge workflows:
- Directly merging an individual pull request.
- Adding a pull request to a merge queue.
- Merging a group of stacked pull requests.
- Handling individual or stacked pull requests through an asynchronous operation.
The operational model is a two-stage process. A client submits a merge request with HTTP PUT. GitHub returns a request identifier, which the client uses with a GET request to poll the operation’s status. The supplied documentation does not define a universal polling interval, backoff strategy, client timeout, retry policy, or complete list of terminal status values, so teams should consult the endpoint’s current reference before finalizing an implementation.
GitHub recommends the asynchronous API for programmatic merges instead of the synchronous REST merge endpoint or GraphQL mutations. The GitHub announcement describes the API’s general availability and supported merge scenarios.
Why stacked pull requests are a major use case
Stacked pull requests are ordered chains of pull requests in the same repository. A stack can represent a larger change as several dependent, reviewable units. The asynchronous API is required when a stack is merged through the API; legacy synchronous merge endpoints and GraphQL mutations cannot merge a stack.
A stacked merge includes the requested pull request and every lower pull request in the stack. The operation is atomic: the complete group merges, the complete group enters the merge queue, or none of it does. A pull request in the middle of a stack cannot be merged in isolation through this workflow.
There is also an important timing distinction. At submission, GitHub checks basic pull-request state. Branch protection and repository rules are evaluated later, when the background merge runs. If those checks fail, the result is reported through status polling. A successful submission therefore should not be treated as proof that the merge has completed successfully.
The stacked pull request API documentation notes that a stacked operation can involve several pull requests and may take a few minutes. It does not provide a guaranteed duration.
Merge queues require CI preparation
Teams using merge queues need to account for how GitHub validates queued changes. Merge queues create temporary merge-group branches, and required checks must run and report against those merge groups. For GitHub Actions workflows, required checks need to handle the merge_group event in addition to the events already used by the project.
Queue configuration can include the merge method, build concurrency, status-check timeout, merge limits, and minimum-group wait time. When a stacked pull request enters a queue, the pull requests are added in order. Removing or ejecting one pull request also removes pull requests above it in the stack.
According to GitHub’s merge queue documentation, merge queues are available in public repositories owned by organizations and in private repositories owned by organizations using GitHub Enterprise Cloud. Those rules describe merge-queue availability, not a complete availability matrix for the asynchronous endpoint itself.
Authentication and permissions remain implementation details
As with other GitHub REST API requests, clients generally authenticate with a token supplied through the Authorization header. GitHub documents personal access tokens, GitHub App tokens, and GITHUB_TOKEN in GitHub Actions as supported token categories.
The caller still needs sufficient authority to merge the targeted pull request and satisfy the applicable repository rules. GitHub also documents an optional ability to bypass rules when the caller has permission to do so. That capability should be treated as privileged automation, not as a general way to avoid branch protection.
The supplied endpoint material does not establish the asynchronous API’s complete fine-grained permission requirements, token configuration, or bypass permission mapping. Teams should verify those details against the current endpoint documentation before deploying production automation.
Important limitations for stacked pull requests
Stacked pull requests must use branches from the same repository. Cross-fork stacks are not supported, and stacked pull requests are not supported in GitHub Desktop. The feature supports merge commits, squash merges, rebases, and merge queues.
Although the async merge API is generally available, GitHub’s stacked pull request documentation labels stacked pull requests as a public-preview feature and subject to change. Organizations adopting stacks should account for that status when designing long-lived tooling.
The supplied documentation also does not establish whether an asynchronous merge request can be explicitly canceled, whether submissions have complete idempotency guarantees, or whether polling has separate rate-limit treatment. Removing a pull request from a merge queue is documented, but that should not be assumed to mean that an in-flight asynchronous merge request can be canceled.
What you should do
- Review existing merge automation. Identify workflows that use the synchronous REST merge endpoint or GraphQL mutations. GitHub recommends moving programmatic merge behavior to the asynchronous API.
- Design for a submission-and-status lifecycle. Store the returned request ID and distinguish submission success from final merge success. Do not hard-code polling, retry, timeout, or cancellation behavior as though GitHub has published universal guidance for those details.
- Use the async API for stacks. Legacy synchronous endpoints and GraphQL mutations are not the API path for merging stacked pull requests.
- Update queue-aware CI. If your repository uses merge queues, ensure required checks run for merge-group events and report results for temporary merge-group branches.
- Review permissions before enabling bypass. Use appropriately scoped credentials, protect token values, and verify that the caller is authorized under the repository’s branch protection or ruleset configuration.
- Validate repository and plan availability. Confirm that the target repository supports the required merge-queue or stacked-pull-request workflow. The available documentation does not provide a complete matrix for every repository type, account plan, geography, or GitHub Enterprise deployment.
For teams building deployment controls, repository bots, or internal developer platforms, the main change is architectural: merge requests can now be modeled as background jobs whose final outcome must be observed. That is especially important for stacked operations, where several pull requests and multiple layers of repository rules may be involved.
Sources
- GitHub: Async merge API generally available
- GitHub documentation: Stacked pull request APIs and webhooks
- GitHub documentation: Stacked pull requests
- GitHub documentation: Merging stacked pull requests
- GitHub documentation: Managing a merge queue
- GitHub documentation: Merging a pull request with a merge queue
- GitHub documentation: Authenticating to the REST API
- GitHub documentation: Creating rulesets for a repository
