9 min read - GitHub's Async Merge API: Build a Merge Worker, Not a Button

On 1 October 2026, GitHub made its asynchronous merge API generally available and recommended it for programmatic pull-request merges. The endpoint can merge directly or submit work to a merge queue, and it is the only merge API that supports stacked pull requests. A caller sends a request, receives an identifier and checks the result later.

A successful submission no longer proves that code landed. The worker has to remember what it requested, reconcile later results and distinguish a queued change from a merged one. Treating the endpoint as a slower version of the old merge call creates false deployment signals, noisy retries and gaps in the audit trail.

For an engineering lead or platform owner, the migration decision is therefore about workflow design. The API is ready for production use; your merge bot may not be.

A 202 response means accepted, not merged

GitHub's release announcement says clients submit a PUT request and poll with the returned request ID. The REST documentation defines the important outcomes:

There is a second terminal path after enqueued. GitHub says that result will not change when the queue eventually merges the pull request. The worker must then check the pull request's merge state or consume the appropriate repository event. If an internal dashboard treats enqueued as merged, release notes, deployment triggers and change records can move ahead of the code.

Store the external UUID before acknowledging the job to your own queue. The record should also contain the repository, pull-request number, expected head SHA, requested merge action, requester, submission time and current state. This gives a restarted worker enough information to continue without reconstructing intent from logs.

Make the state machine explicit

A small state machine is easier to operate than a collection of webhook callbacks and retry branches. One practical model is:

ready -> submitting -> pending -> merged
                         |
                         +------> enqueued -> observing_pr -> merged
                         |
                         +------> failed -> investigate_or_retry

The worker should own transitions, while webhooks and polling provide evidence. A webhook can speed up reconciliation, but it should not be the only path; deliveries can arrive late, be duplicated or fail. Polling needs an upper bound because GitHub retains an asynchronous result for 24 hours after its latest update. After that, the result endpoint returns 404, according to the API reference.

Define two deadlines. The first limits how long a job may remain pending before an operator sees an alert. The second stops reconciliation before the result expires, then checks the pull request directly. Do not convert an expired UUID into an automatic resubmission: the original operation may already have changed repository state.

This is ordinary distributed-systems work. AWS's guidance on idempotent APIs explains why a missing response does not reveal whether a side effect happened. Its advice is independent of GitHub, but the failure is the same: retrying a state-changing call without reconciliation can repeat work or confuse ownership. For this endpoint, a 409 response can return the UUID and options of an existing pending merge request. Persist that identity and continue observing it instead of creating a second local story about the same pull request.

Pin the code you approved

The request body accepts the pull request's expected head SHA. Use it. A reviewer may approve one commit while an automation later attempts to merge another after the branch moves. Supplying the SHA turns that race into a visible conflict instead of silently broadening the approval.

Capture the same value in the internal job record and compare it again before reporting completion. If the head changes while a request is pending, stop the surrounding release workflow until the final state is understood. Do not rewrite the expected SHA inside a retry loop; that would turn a safety condition into “merge whatever is current.”

Branch protection and repository rules still decide whether a change may land. GitHub documents that only basic pull-request state is checked when an asynchronous request is submitted; rules are evaluated later during execution. A 202 is therefore an intake acknowledgement, not a policy verdict.

NIST's DevSecOps source-code management scenario describes branch and merge protection as the control that prevents unapproved code from entering the main codebase. Keep that control on the repository side. The bot should request a merge and report the result, not reproduce approvals and checks in application code that can drift from repository policy.

GitHub also notes that the API can bypass rules when the caller has permission. That is a capability, not a sensible default. Give the bot the narrowest token and repository scope it needs, deny bypass in the normal path and log any separately authorised emergency procedure. A convenient merge service should not become a standing route around CODEOWNERS, required reviews or security checks.

Our AI-assisted development guardrails apply the same separation of duties to generated changes: automation may prepare work, while repository policy controls what reaches the protected branch.

Queue submission and merge completion are different service levels

A merge queue adds another clock. The asynchronous request can finish successfully when the pull request enters the queue, yet the queue may later rebuild, eject or merge it. Operations teams need separate measures for API acceptance, queue admission and final merge.

Track at least these fields:

• submission-to-terminal time for the asynchronous request;
• queue admission-to-merge time, including ejections and re-entry;
• failures grouped by basic state, policy, stale SHA, permissions and service errors;
• the age and count of jobs whose stored state disagrees with GitHub;
• every bypass request, whether attempted, denied or separately authorised.

Avoid one blended “merge success rate.” It hides the difference between a reliable bot and an overloaded queue, and it can make a protection-rule failure look like platform downtime. Owners need the component that failed before they can choose the right response.

The same distinction belongs in deployment automation. Trigger a deployment from the repository's confirmed merged commit or a protected-branch event, not from the merge request's 202 response or an enqueued result. A production change record should point to the landed commit OID.

Stacks increase the size of one decision

GitHub's stacked pull-request API documentation says a request against a stacked pull request includes all open pull requests below it. The operation is atomic: the eligible group merges or joins the queue together, or none of it does. Rules are checked later, and a failure is returned through the asynchronous result.

The async merge API is generally available, but the stacked pull-request feature remains in public preview as of the 2 October review. Keep those lifecycle labels separate in a rollout decision. A team can migrate ordinary merges to the new endpoint without enabling stacks.

If stacks are in scope, the approval screen and audit record should show the entire down-stack set rather than only the pull request named in the request URL. Record each pull-request number, head SHA, position and review state. Otherwise an operator may believe they approved one change while the operation covers several dependent changes.

Start with standalone pull requests on a low-risk repository. Then test a protected branch, a stale SHA, a draft pull request, an existing pending request, queue admission and a forced rule failure. Exercise worker restart during pending, delayed webhook delivery and result expiry. Add stacks only after the ordinary path produces trustworthy state and audit records.

A migration contract for the platform team

Before changing the production bot, write down the contract that product and operations teams can inspect:

1. The source of merge intent and who may create it.
2. The exact pull request, head SHA, merge action and repository policy that apply.
3. How the worker stores the UUID, polls, receives events and reconciles disagreements.
4. Which states may trigger release, deployment, notification and incident workflows.
5. Retry limits, expiry handling, manual recovery and the evidence retained for review.
6. Whether stacked pull requests are excluded, piloted or accepted with full-set visibility.

Run the old and new observers side by side without allowing the new worker to merge. Compare their view of eligible pull requests, then enable a small repository set and keep a manual stop. The migration is complete when the worker can recover from interruption and prove the final repository state, not when it receives its first 202.

Exceev's services approach connects delivery policy, engineering changes and team handover. For smaller teams, the right implementation may be a short-lived worker backed by a durable table rather than a new platform. The design test remains the same: can it resume, reconcile and explain every merge decision?

Sources and limitations

We opened and reviewed every source below on 2 October 2026.

• GitHub's 1 October release announcement establishes general availability, the request-and-poll flow, supported merge actions and GitHub's recommendation to use the asynchronous endpoint for programmatic merges.
• GitHub's REST pull-request API reference defines request fields, response codes, result states, the 24-hour result-retention window and the difference between enqueued and merged.
• GitHub's stacked pull-request API documentation documents the preview status, down-stack scope, later rule evaluation and atomic outcome for stacks.
• AWS's article on idempotent APIs supplies independent engineering guidance on retries, uncertain outcomes and side effects.
• NIST's DevSecOps source-code management scenario supplies independent guidance on approved review and enforced branch and merge protection.

We did not call the new endpoint, test GitHub's infrastructure, measure queue performance or verify plan availability for a specific organisation. GitHub can change API behaviour, permissions, preview status and documentation after the review date. Examples describe an implementation pattern, not a claim about Exceev or a client environment. Teams should validate token scope, repository rules, webhook delivery, audit retention and rollback in their own organisation.