Skip to content

Commit 4ddb50d

Browse files
skarimtalum
andauthored
Apply batched suggestions from code review
Co-authored-by: Tracy Lum <11878752+talum@users.noreply.github.com> Co-authored-by: Sameen Karim <skarim@github.com>
1 parent 67774e4 commit 4ddb50d

1 file changed

Lines changed: 6 additions & 6 deletions

File tree

‎docs/src/content/docs/reference/merge-api.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ description: Reference for the asynchronous merge API — the required method fo
55

66
Stacked pull requests are merged through a new **asynchronous merge API**. Because a stack merge can involve several pull requests that may take up to a few minutes to merge, the merge runs in the background: you submit a merge request and then poll for its result.
77

8-
This is the **required method for merging stacked PRs**. A stack cannot be merged with the legacy synchronous [merge endpoints](https://docs.github.com/rest/pulls/pulls#merge-a-pull-request) or [mutations](https://docs.github.com/en/graphql/reference/pulls#mutation-mergepullrequest). When you merge a stacked pull request, every pull request in the stack up to and including the one you request is merged into the base branch.
8+
This is the **required method for merging stacked PRs**. A stack cannot be merged with the legacy synchronous [merge endpoints](https://docs.github.com/rest/pulls/pulls#merge-a-pull-request) or [mutations](https://docs.github.com/en/graphql/reference/pulls#mutation-mergepullrequest). When you merge a stacked pull request, every pull request in the stack up to and including the one you request is merged or queued to merge into the base branch.
99

1010
## How it works
1111

1212
Merging is a two-step flow:
1313

14-
1. **Submit** a merge request with `PUT .../merge-async`, then read the `status`. Only a `pending` response includes a `uuid` to poll. The submit can also resolve immediately to `merged` (the pull request was already merged) or `failed` (the pull request is closed or a draft), both of which are terminal.
14+
1. **Submit** a merge request with `PUT .../merge-async`, then read the `status`. Only a `pending` response includes a `uuid` to poll. The submission may resolve immediately to `merged` (the pull request was already merged) or `failed` (the pull request is closed or a draft), both of which are terminal. It may also resolve to `enqueued` (the pull request was already added to the merge queue).
1515
2. **Poll** a `pending` request for its result with `GET .../merge-async/{uuid}` until the `status` is no longer `pending`.
1616

1717
Only basic pull request state is checked when you submit (the PR must be open and not a draft). Branch protection and repository rules are evaluated later, when the merge actually runs, and a rule failure is reported as a `failed` result while polling. A stack merge request is **atomic**: either the whole group of pull requests lands (or is added to the merge queue), or none of it does.
@@ -22,17 +22,17 @@ Only basic pull request state is checked when you submit (the PR must be open an
2222
PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge-async
2323
```
2424

25-
Merges the pull request (and, for a stacked PR, everything below it in the stack) into the base branch in the background. Only a `pending` response returns a `uuid` to fetch the result. The submit can also resolve immediately — `merged` if the pull request was already merged, or `failed` if it cannot be merged (for example, it is closed or a draft).
25+
Merges the pull request (and, for a stacked PR, everything below it in the stack) into the base branch in the background. Only a `pending` response returns a `uuid` to fetch the result. The submit can also resolve immediately — `merged` if the pull request was already merged, or `failed` if it cannot be merged (for example, it is closed or a draft). It may also resolve to `enqueued` (the pull request was already added to the merge queue).
2626

2727
All body fields are optional.
2828

2929
| Body field | Type | Description |
3030
|------------|------|-------------|
31-
| `merge_method` | `string` | The merge method: `merge`, `squash`, or `rebase`. Defaults to a merge commit. |
32-
| `merge_action` | `string` | How to merge: `default` (recommended), `direct_merge`, or `merge_queue`. `default` picks the most appropriate option — it merges directly, or adds the stack to the base branch's merge queue when the branch requires one. `direct_merge` forces a direct merge; `merge_queue` forces the merge queue, if available. Omitting this field is equivalent to `default`. |
31+
| `merge_method` | `string` | The merge method: `merge`, `squash`, or `rebase`. Defaults to a merge commit. Not supported on `merge_queue` merge actions. |
32+
| `merge_action` | `string` | How to merge: `default` (recommended), `direct_merge`, or `merge_queue`. `default` picks the most appropriate option — it merges directly, or adds the stack to the base branch's merge queue when the branch requires one. `direct_merge` forces a direct merge; `merge_queue` uses the merge queue, if available. Omitting this field is equivalent to `default`. |
3333
| `commit_title` | `string` | Title for the automatic commit message. Not supported on `merge_queue` merge actions. |
3434
| `commit_message` | `string` | Extra detail to append to the automatic commit message. Not supported on `merge_queue` merge actions. |
35-
| `sha` | `string` | SHA that the pull request head must match to allow the merge. If the PR head does not match the provided SHA, the merge is cancelled. |
35+
| `sha` | `string` | SHA that the pull request head must match to allow the merge. If the PR head does not match the provided SHA, the merge is rejected. |
3636

3737
```sh
3838
echo '{"merge_method": "squash", "merge_action": "default"}' | \

0 commit comments

Comments
 (0)