For a GitHub asynchronous merge, record what you observed, the message it supports and who owns the next check. This worksheet helps reviewers catch a status update that promises more than its evidence establishes.
A release bot can be technically responsive and still give an unhelpful answer. “Done” might mean it submitted an operation, entered a queue, or observed a completed merge. This guide offers a proposed observation record for teams updating a merge integration. It is not a report of a live merge test.
What changed on October 1?
GitHub announced general availability of its asynchronous merge API on October 1, 2026. GitHub recommends this route for programmatic merges and says it supports individual and stacked pull requests, direct merges and merge queues. Submission and result lookup are separate operations.
The practical migration question is therefore bigger than “Did we replace the endpoint?” Decide which observation allows each message in your own product. A status label that is clear to the API author may be too broad for the person waiting to ship.
Read the result before composing the message
The official REST reference distinguishes an unfinished pending result from merged, enqueued and failed outcomes. enqueued confirms queue admission; its result will not change when the PR later merges. Check that PR separately. merged includes a commit identifier, and failed includes a reason. A saved result expires 24 hours after its latest update.
Before an authorized trial, write down the repository, PR link, reviewed head revision, intended action, merge method and person responsible for the result. Keep the returned request ID with that record. Do not put access tokens or authorization headers in a ticket, screenshot or chat message.
Use a message contract, not one generic success label
The following wording is an editorial proposal for your bot or dashboard. Adapt it to the actual evidence you collect; the table is not a replacement for the API schema.
| Observation in your record | Suggested message | Next responsibility |
|---|---|---|
| Request accepted; outcome unresolved | Merge requested; waiting for the result. | The integration keeps the observation open. |
| Queue admission observed | Added to the merge queue; merge not yet confirmed. | The owner follows the PR to its eventual outcome. |
| Merge confirmed with a commit | Merged; review the linked commit. | The release owner checks any separate deployment process. |
| Failure observed | This merge request failed; review the recorded reason. | A named person decides the correction and next attempt. |
| Observation unavailable | Outcome unknown; checking current PR state. | The integration avoids presenting a guess as success. |
For example, imagine a fictional bot that posts “Ready for production” as soon as it receives a queue-admission result. Change the acceptance test to ask what that sentence promises. If it promises a merge, the test needs evidence from the PR. If it promises a deployment, it needs a separate deployment observation too. Do not make the test easier by quietly changing the meaning of “ready.”
Plan for a lost response or an expired receipt
A useful incident record says what was observed before contact was lost. “The client timed out after submission; no result was captured” is more actionable than “merge failed.” First inspect current state and any saved operation identity. A missing observation is a reason to investigate, not automatic permission to submit another mutation.
Give recovery an owner and a next check. If the recorded options differ from the operation you intended, stop and reconcile that difference before another attempt. Do not bypass repository rules or broaden credentials to force a green outcome. For a stack, also review the included pull-request boundary; this article deals with observing completion, not choosing the merge scope.
Polling needs a policy as well. GitHub's REST best practices recommend avoiding unnecessary polling and concurrent requests. Where polling is needed, honor x-poll-interval if supplied; on rate limiting, follow retry-after or the documented reset/backoff guidance. Choose your own monitoring deadline and escalation owner rather than inventing a universal “merge must finish in ten seconds” rule.
Copy this observation and handoff record
- Case: [local case ID] / [repository and PR link] / [reviewed head revision]
- Intent: [authorized action and method] / [scope reviewed by whom]
- Submission: [time and timezone] / [HTTP status] / [request ID if returned]
- Latest observation: [time] / [response state or unavailable] / [safe reason, if any]
- PR outcome: [merged, not merged, or not checked] / [commit link when established]
- Message sent: [exact reader-facing wording] / [evidence supporting it]
- Next: [bounded check or correction] / [owner] / [escalation condition]
Use synthetic response fixtures to review your labels before a live trial. Include an unresolved request, queue admission, confirmed merge, reported failure and unavailable observation. Those are proposed test cases, not claimed results. Finish when each label says only what its evidence establishes and every unresolved case has a clear next action.