gh programmatic pull request merging with the async merge API
Introduced 2026-10-01 · score 0.96
HOW TO USE IT
For individual or stacked PRs, submit a merge request with `PUT`; poll the result with `GET` using the returned UUID. Set `merge_action` for direct or queued merges, and set `bypass_rules` only when authorized.
curl -L -X PUT -H "Accept: application/vnd.github+json" -H "Authorization: Bearer <TOKEN>" -H "X-GitHub-Api-Version: 2026-03-10" "https://api.github.com/repos/<OWNER>/<REPO>/pulls/<PULL_NUMBER>/merge-async" -d '{"merge_action":"default"}'curl -L -H "Accept: application/vnd.github+json" -H "Authorization: Bearer <TOKEN>" -H "X-GitHub-Api-Version: 2026-03-10" "https://api.github.com/repos/<OWNER>/<REPO>/pulls/<PULL_NUMBER>/merge-async/<UUID>"WHY THIS HELPS
Programmatically merge individual or stacked pull requests, add pull requests to a merge queue, or merge pull requests directly in a busy repository.
BEFORE THIS CHANGE
Use the synchronous REST endpoint or GraphQL mutations to merge pull requests.
REQUIREMENTS AND LIMITATIONS
- Availability: generally available
- owner (required): Repository account owner.
- repo (required): Repository name without `.git`.
- pull_number (required): Pull request number.
- merge_action: `default` uses a queue if configured or merges directly; `direct_merge` skips the queue; `merge_queue` adds to a queue. Allowed values are mutually exclusive; omission defaults to `default`.
- merge_method: Direct merge method: `merge`, `squash`, or `rebase`; only for direct merges. Values are mutually exclusive.
- commit_title: Automatic commit title; only for direct merges.
- commit_message: Extra detail in automatic commit message; only for direct merges.
- sha: Expected PR head SHA; if omitted, current head is used and a later push before execution cancels the merge.
- bypass_rules: Bypass repository rules the authenticated actor may bypass; defaults to `false`.
- uuid (required): UUID returned by the merge request; identifies the result to fetch.
- Prerequisite: Fine-grained tokens must have `Contents` repository permission (write). Supported token types include GitHub App user and installation tokens, and fine-grained personal access tokens.
- Prerequisite: The async result endpoint also requires `Contents` repository permission (write) for fine-grained tokens.
- Bypassing rules requires permission.
FIRST-PARTY EVIDENCE
- https://github.blog/changelog/2026-10-01-github-async-merge-api-generally-available
- https://docs.github.com/en/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously
- https://docs.github.com/en/rest/pulls/pulls?apiVersion=2026-03-10#get-the-result-of-an-asynchronous-merge
Check the installed version and the source before using it. Entry JSON