GitHub API (unofficial showcase)
PUT/repos/{owner}/{repo}/pulls/{pull_number}/merge-async

Merge a pull request asynchronously

Merges a pull request into the base branch in the background or adds it to a merge queue. Background processing allows certain types of errors to be retried and reduces the risk of timeouts for complex merges.

This is the required API for merging stacked pull requests. For a stacked pull request, the operation includes all open downstack pull requests.

A new asynchronous merge request returns a 202 response with a UUID that can be used to fetch the result of the merge. If another asynchronous merge request is already pending for this pull request, a 409 response returns that request's UUID and merge options instead.

If the pull request is already merged or already in a merge queue, a 200 response is returned immediately. A merged result includes the merge commit OID. An enqueued result means the pull request was added to the merge queue, not that it has merged.

If the pull request cannot be merged (e.g. because it is closed, or still a draft) this result will be returned immediately with a 400 response status. Branch protection rules and repository rules are not run at this stage, only basic pull request state checks are performed.

3 parameters · 6 body fields
ownerstringrequired
The account owner of the repository. The name is not case sensitive.
repostringrequired
The name of the repository without the `.git` extension. The name is not case sensitive.
pull_numberintegerrequired
The number that identifies the pull request.
commit_titlestringoptional
Title for the automatic commit message. Only supported for direct merges.
commit_messagestringoptional
Extra detail to append to automatic commit message. Only supported for direct merges.
shastringoptional
SHA that pull request head must match to allow merge. If not provided, the current head of the PR at the time of the request will be used; if the PR is pushed in between the merge being requested and being executed, the merge will be cancelled.
merge_methodstringoptional
The merge method to use for a direct merge. Only supported for direct merges.
Allowed:mergesquashrebase
merge_actionstringoptional
The action that will be taken to merge the pull request. `direct_merge` merges the pull request directly without using a merge queue; `merge_queue` adds the pull request to a merge queue; `default` uses a merge queue if one is configured for the target branch, or merges directly otherwise. If omitted, defaults to `default`.
Allowed:defaultdirect_mergemerge_queue
bypass_rulesbooleanoptional
Whether to bypass repository rules that the authenticated actor is permitted to bypass.
Default:false

7 status codes
200if the pull request was already merged, or is already in a merge queue
statusstringrequired
Allowed:pendingmergedenqueuedfailed
detailsobjectrequired
When the asynchronous merge request is pending
202if the merge request was accepted and will run in the background
statusstringrequired
Allowed:pendingmergedenqueuedfailed
detailsobjectrequired
When the asynchronous merge request is pending
400if the pull request is not ready to be merged, e.g. because it is closed
statusstringrequired
Allowed:pendingmergedenqueuedfailed
detailsobjectrequired
When the asynchronous merge request is pending
403Forbidden
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
404Resource not found
messagestringoptional
documentation_urlstringoptional
urlstringoptional
statusstringoptional
409if there is an existing merge request already enqueued for this pull request
statusstringrequired
Allowed:pendingmergedenqueuedfailed
detailsobjectrequired
When the asynchronous merge request is pending
422Validation failed, or the endpoint has been spammed.
messagestringrequired
documentation_urlstringrequired
errorsarray<object>optional

Error handling

A 400 is returned: if the pull request is not ready to be merged, e.g. because it is closed. A 403 is returned: Forbidden. A 404 is returned: Resource not found. A 409 is returned: if there is an existing merge request already enqueued for this pull request. A 422 is returned: Validation failed, or the endpoint has been spammed.