You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7c27ea3
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -154,11 +154,11 @@ Every PR in a stack must meet the same merge requirements as a PR targeting the
154
154
155
155
### How does merging a stack of PRs differ from merging a regular PR?
156
156
157
-
Stacks merge from the bottom up as a single atomic operation. When you click merge on a PR in a stack, that PR and all unmerged PRs below it land on the base branch together. PRs above remain open, and the remaining stack is automatically rebased so the next PR targets `main` directly.
157
+
Stacks merge from the bottom up. When you click merge on a PR in a stack, that PR and all unmerged PRs below it land on the base branch together; PRs above remain open, and the remaining stack is automatically rebased so the next PR targets your base branch directly. With a direct merge the group lands as a single atomic operation; through a merge queue the PRs enter the queue together and are evaluated individually, from the bottom up.
158
158
159
159
### What happens when you merge a PR in the middle of the stack?
160
160
161
-
When you click merge on a PR in the middle of the stack, that PR and all unmerged PRs below it land on the base branch together as a single atomic operation, ordered from the bottom up in the resulting history. PRs above the selected one remain open. After the merge, the lowest unmerged PR is updated to target the stack base directly, and a cascading rebase runs across the remaining branches.
161
+
When you click merge on a PR in the middle of the stack, that PR and all unmerged PRs below it land on the base branch together, ordered from the bottom up in the resulting history. PRs above the selected one remain open. After the merge, the lowest unmerged PR is updated to target the stack base directly, and a cascading rebase runs across the remaining branches.
162
162
163
163
It is not possible to merge a middle PR in isolation: the PRs below it always merge with it.
164
164
@@ -206,13 +206,14 @@ When you merge a stack using the merge commit strategy, it creates **one merge c
206
206
207
207
### How does rebase merge work?
208
208
209
-
With rebase merge, the commits from each PR in the stack are replayed onto the base branch, creating a linear history without merge commits. The full set of commits lands as a single atomic operation.
209
+
With rebase merge, the commits from each PR in the stack are replayed onto the base branch, creating a linear history without merge commits. The full set of commits lands on the base branch.
210
210
211
211
### Do all PRs get merged at once or one at a time?
212
212
213
-
All PRs in the stack land in a single atomic operation. When you click merge on a PR, that PR and all unmerged PRs below it are merged together onto the base branch at the same time, ordered from the bottom up in the resulting history. PRs above the selected one remain open.
213
+
It depends on the merge method:
214
214
215
-
This applies whether or not a merge queue is enabled. With a merge queue, the same atomic landing happens once the stack's merge group reaches the front of the queue.
215
+
- **Direct merge** — All the included PRs land in a single atomic operation. The selected PR and every unmerged PR below it are merged together onto the base branch at once, ordered from the bottom up. Either the whole group lands, or if any part fails, none of it does.
216
+
- **Merge queue** — The PRs enter the queue together and are evaluated individually, from the bottom up. If a PR fails while in the queue, it and all its descendants are ejected, while the PRs below it are unaffected.
216
217
217
218
### Can I merge only part of a stack? What happens to the remaining unmerged PRs?
218
219
@@ -228,15 +229,18 @@ Closing a PR in the middle of the stack will block all PRs above it from being m
228
229
229
230
### What happens when there is an error merging a PR in the middle of a stack?
230
231
231
-
Pre-merge checks run before any merge attempt, but a merge can still fail (e.g., due to an unexpected merge conflict or intermittent failure). If a failure occurs partway through, merging stops at that PR. PRs below it that successfully merged remain landed on the base branch; the failed PR and PRs above it stay open. Resolve the issue on the failed PR and retry to land the rest of the stack.
232
+
Pre-merge checks run before any merge attempt, but a merge can still fail (e.g., due to a merge conflict or intermittent failure). The behavior depends on the merge method:
233
+
234
+
- **Direct merge** — The merge is atomic. If any part fails, the entire operation is rolled back and nothing is merged.
235
+
- **Merge queue** — Because each PR is evaluated individually, a failure ejects that PR and all its descendants (the PRs stacked above it) from the queue, while the PRs below it are unaffected. You can fix the issue on the failed PR and requeue the ejected PRs.
232
236
233
237
### Do Stacked PRs support merge queue?
234
238
235
-
Yes, Stacked PRs fully support merging via merge queue. When you merge a stack through the merge queue:
239
+
Yes, Stacked PRs fully support merging via GitHub merge queue. When you merge a stack through the merge queue:
236
240
237
-
- **All PRs in the stack are added to the queue** in the correct order, ensuring a linear sequence.
238
-
- **If a PR is removed or ejected from the merge queue**, all PRs above it in the stack are also ejected and removed from the queue.
239
-
- **Stacks are kept in the same merge group on a best-effort basis.** To keep a stack together, the merge queue allows the merge group to exceed its configured max size by up to 50%. If the stack is too large to fit within that buffer, it splits across consecutive merge groups: as much of the stack as fits goes into the current group, and the remaining PRs continue in subsequent groups until the full stack has landed.
241
+
- **All PRs in the stack enter the queue together** in the correct order and are evaluated individually, from the bottom up.
242
+
- **If a PR is ejected from the merge queue** (for example, because it fails), that PR and all its descendants are ejected too, while the PRs below it are unaffected.
243
+
- **The queue makes a best-effort attempt to keep the stack together** in a single merge group. If the stack is too large to fit, it lands across consecutive merge groups: as much of the stack as fits goes into the current group, and the remaining PRs continue in subsequent groups until the full stack has landed. The stack order is preserved, so downstack PRs are merged before upstack PRs.
Copy file name to clipboardExpand all lines: docs/src/content/docs/guides/stacked-prs.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,7 +23,7 @@ Each PR in a stack shows only the diff for its layer — the changes between its
23
23
24
24
## Merging a Stack
25
25
26
-
Merging is driven by a single action: **click Merge on the highest PR you want to land, and that PR plus every unmerged PR below it merges in one atomic operation.** You do not need to merge PRs one at a time, unless you choose to.
26
+
Merging is driven by a single action: **click Merge on the highest PR you want to land, and that PR plus every unmerged PR below it are merged together, from the bottom up.** You do not need to merge PRs one at a time, unless you choose to.
27
27
28
28
-**To land the whole stack**, merge the **top** PR — every PR below it lands with it in a single step.
29
29
-**To land part of the stack**, merge a lower PR — the PRs below it come along, and the PRs above stay open.
Copy file name to clipboardExpand all lines: docs/src/content/docs/index.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
---
2
2
title: GitHub Stacked PRs
3
-
description: Break large changes into small, reviewable, stacked pull requests with first-class GitHub support.
3
+
description: Break large changes into small, reviewable, stacked pull requests on GitHub.
4
4
template: splash
5
5
hero:
6
6
title: GitHub Stacked PRs
7
-
tagline: Break large changes into small, reviewable pull requests that build on each other — with native GitHub support and the <code>gh stack</code> CLI.
7
+
tagline: Break large changes into small, reviewable pull requests. Manage your stacks on GitHub, with the <code>gh stack</code> CLI, or via our APIs.
8
8
actions:
9
9
- text: Quick Start
10
10
link: /gh-stack/getting-started/quick-start/
@@ -55,7 +55,7 @@ GitHub understands stacks end-to-end: the pull request UI shows a **stack map**
55
55
56
56
**While the `gh stack` CLI makes the local workflow seamless, it is entirely optional.** You can create and manage Stacked PRs directly via the GitHub UI, the API, or your standard Git workflow. If you choose to use the CLI, it handles creating branches, managing rebases, pushing to GitHub, and creating PRs with the correct base branches. On GitHub, the PR UI gives reviewers the context they need — a stack map, focused diffs for each layer, and proper rules enforcement.
57
57
58
-
When you're ready to merge, click **Merge** on the highest PR you want to land — that PR **and every unmerged PR below it merge together in a single, atomic operation**. Merge the top PR to land the whole stack in one click, or merge a lower PR to land just part of it (the PRs above stay open). After a partial merge, the remaining PRs are automatically rebased so the lowest unmerged PR targets the updated base branch.
58
+
When you're ready to merge, click **Merge** on the highest PR you want to land — that PR **and every unmerged PR below it are merged together, from the bottom up**. Merge the top PR to land the whole stack in one click, or merge a lower PR to land just part of it (the PRs above stay open). After a partial merge, the remaining PRs are automatically rebased so the lowest unmerged PR targets the updated base branch.
Copy file name to clipboardExpand all lines: docs/src/content/docs/introduction/overview.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,7 +55,7 @@ This ensures that every layer of the stack meets the same quality bar before it
55
55
56
56
### Merging Stacks
57
57
58
-
You can merge your entire stack, a single PR, or a portion of the stack spanning multiple PRs. When you click **Merge** on any PR, that PR **and every unmerged PR below it land together in a single atomic operation**. So you can:
58
+
You can merge your entire stack, a single PR, or a portion of the stack spanning multiple PRs. When you click **Merge** on any PR, that PR and every unmerged PR below it are merged together, from the bottom up. So you can:
59
59
60
60
-**Land the entire stack in one click** by merging the top PR — every PR below it comes with it.
61
61
-**Land part of the stack** by merging a mid-stack PR — the PRs below it come along, and the PRs above stay open.
@@ -64,10 +64,10 @@ You can't merge a PR while leaving an unmerged PR below it behind. Merging a sta
64
64
65
65
GitHub supports two merge methods:
66
66
67
-
-**Direct merge** — Merges the selected PR and all unmerged PRs below it in a single operation, as long as all conditions are met.
68
-
-**Merge queue** — Works as usual but is stack-aware. For example, if the bottom PR is removed from the queue, all other PRs in the stack are also removed.
67
+
-**Direct merge** — The selected PR and all unmerged PRs below it land in a single **atomic**operation. Either the whole group merges, or if any part fails, nothing is merged and the operation is rolled back.
68
+
-**Merge queue** — The PRs enter the queue together and each PR is evaluated **individually**, from the bottom up. If a PR fails while in the queue, that PR and all its descendants are ejected from the queue, while prior PRs are unaffected. The queue makes a best-effort attempt to keep the whole stack in a single merge group; if the stack is too large to fit, it lands across consecutive groups. If PRs are split across merge groups, the stack order is preserved so downstack PRs are merged before upstack PRs.
69
69
70
-
The resulting commit history is the same as if each PR had been merged individually, starting from the bottom.
70
+
In both methods, the resulting commit history is the same as if each PR had been merged individually, starting from the bottom.
Copy file name to clipboardExpand all lines: docs/src/content/docs/reference/graphql-api.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,7 +59,7 @@ An edge in a `PullRequestStackEntryConnection`.
59
59
60
60
## Example
61
61
62
-
Read a pull request's stack, its position, and every pull request in the stack:
62
+
Read a pull request's stack, its position, and the first 5 pull requests in the stack:
63
63
64
64
```graphql
65
65
{
@@ -74,7 +74,7 @@ Read a pull request's stack, its position, and every pull request in the stack:
74
74
number
75
75
size
76
76
baseRefName
77
-
entries(first: 20) {
77
+
entries(first: 5) {
78
78
totalCount
79
79
nodes {
80
80
position
@@ -92,3 +92,5 @@ Read a pull request's stack, its position, and every pull request in the stack:
92
92
```
93
93
94
94
The pull request's own `baseRefName` is the branch it directly targets (the PR below it in the stack), while `stack.baseRefName` is the branch the entire stack ultimately targets. These differ for every PR in the stack except the bottom one.
95
+
96
+
`entries` is a paginated connection (ex: `first: 5` returns up to the first 5 entries). Check the `totalCount` for the full size and if a stack has more entries, page through the rest with the connection's `pageInfo`.
Copy file name to clipboardExpand all lines: docs/src/content/docs/reference/rest-api.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -178,7 +178,7 @@ gh api --method POST repos/OWNER/REPO/stacks/42/unstack
178
178
179
179
### The stack resource
180
180
181
-
The list, get, create, add, and unstack endpoints all return the stack resource:
181
+
Each stack is represented by the following resource. The get, create, and add endpoints return a single stack; the list endpoint returns an array of them; and unstack returns the remaining merged stack, or `204 No Content` when the stack is dissolved.
Copy file name to clipboardExpand all lines: docs/src/content/docs/reference/webhooks.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -109,7 +109,7 @@ The `stack` object is also available in GitHub Actions workflow expressions via
109
109
110
110
### Optimizing CI usage
111
111
112
-
Because a workflow runs for every PR in a stack, you can use the `stack` fields to selectively run jobs. For example, if you only plan on merging one PR at a time, you can choose to only run CI for the lowest unmerged PR. Compare the stack's base ref to the PR's own base ref to detect the **lowest unmerged PR**, and compare `position` to `size` to detect the **top PR**:
112
+
Because a workflow runs for every PR in a stack, you can use the `stack` fields to selectively run jobs. For example, if you only plan on merging one PR at a time, you can choose to only run CI for the lowest unmerged PR. Compare the stack's base ref to the PR's own base ref to detect the **lowest unmerged PR**, and compare `position` to `size` to detect the **top PR**. Note that on a standalone PR the `stack` object is `null`, so you can check that to ensure this logic only applies to stacks.
113
113
114
114
```yaml
115
115
jobs:
@@ -119,11 +119,11 @@ jobs:
119
119
- uses: actions/checkout@v4
120
120
121
121
- name: Run for the lowest unmerged PR in the stack
0 commit comments