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
Copy file name to clipboardExpand all lines: docs/src/content/docs/faq.md
+18-2Lines changed: 18 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,7 +75,7 @@ GitHub Actions workflows trigger as if each PR in the stack is targeting the bas
75
75
76
76
### How do I access stack metadata in my GitHub Actions workflow?
77
77
78
-
For advanced use cases, you can access the stack's base ref and base SHA in workflow expressions via `github.event.pull_request.stack`. This property is only present when the PR belongs to a stack.
78
+
For advanced use cases, you can access the stack's metadata in workflow expressions via `github.event.pull_request.stack`. This property is only present when the PR belongs to a stack.
79
79
80
80
```yaml
81
81
jobs:
@@ -89,16 +89,32 @@ jobs:
89
89
run: |
90
90
echo "Stack base ref: ${{ github.event.pull_request.stack.base.ref }}"
91
91
echo "Stack base SHA: ${{ github.event.pull_request.stack.base.sha }}"
92
+
echo "PR ${{ github.event.pull_request.stack.position }} of ${{ github.event.pull_request.stack.size }} in the stack"
92
93
93
94
- name: Run a step only when the stack targets a release branch
Copy file name to clipboardExpand all lines: docs/src/content/docs/guides/stacked-prs.md
+9-6Lines changed: 9 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,14 +21,17 @@ Each PR in a stack shows only the diff for its layer — the changes between its
21
21
-**Review individual PRs** when you're focusing on a specific concern (e.g., reviewing only the API layer).
22
22
-**Use the stack map** to navigate between PRs without going back to the PR list.
23
23
24
-
## Merging from the Bottom Up
24
+
## Merging a Stack
25
25
26
-
Stacks are merged **from the bottom up** — you can merge any number of PRs at once, as long as they form a contiguous group starting from the lowest unmerged PR. For example, in a stack of four PRs, you can merge just the bottom one, or the bottom three together, but you cannot merge only the second and third PRs while leaving the first unmerged. Mid-stack merges are not allowed.
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 PRsone at a time, unless you choose to.
27
27
28
-
1. When the lowest unmerged PR (and any PRs above it that you want to include) meet all merge requirements, merge them.
29
-
2. After the merge, the remaining stack is **automatically rebased** — the next unmerged PR's base is updated to target `main` directly.
30
-
3. The next unmerged PR is now at the bottom and can be reviewed, approved, and merged.
31
-
4. Repeat until the entire stack is landed.
28
+
-**To land the whole stack**, merge the **top** PR — every PR below it lands with it in a single step.
29
+
-**To land part of the stack**, merge a lower PR — the PRs below it come along, and the PRs above stay open.
30
+
-**To land a single PR**, merge the **bottom** PR - only that PR will be merged, and the rest of the PRs stay open.
31
+
32
+
You can merge any contiguous group, as long as it starts from the lowest unmerged PR. In a stack of four PRs you can land just the bottom one, or the bottom three together, but you can't merge only the second and third while leaving the first unmerged — a PR always brings the unmerged PRs below it along. Merging a stacked PR always merges all the unmerged PRs below it as well.
33
+
34
+
When you land only part of a stack, the remaining PRs are **automatically rebased** and retargeted so the next unmerged PR targets your base branch directly and is immediately ready to review and merge.
32
35
33
36
Once the entire stack has landed, it is complete and can't be extended. If you add new branches on top and run `gh stack submit`, the CLI automatically starts a **new** stack rooted at the trunk for those branches (a new PR on a fully merged stack would target the trunk directly rather than chaining onto the merged PRs).
Copy file name to clipboardExpand all lines: docs/src/content/docs/guides/ui.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,17 +7,17 @@ This guide walks through the key UI components and workflows for working with St
7
7
8
8
## Navigating Stacked PRs
9
9
10
-
When a pull request is part of a stack, a **stack navigator** appears in the PR header. This component gives you an at-a-glance view of the entire stack and lets you jump between PRs.
10
+
When a pull request is part of a stack, a **stack map** appears in the PR header. This component gives you an at-a-glance view of the entire stack and lets you jump between PRs.
11
11
12
-
The stack navigator shows:
12
+
The stack map shows:
13
13
14
14
- All PRs in the stack, listed in order from top to bottom
15
15
- Which PR you're currently viewing (highlighted)
16
16
- Clickable links to navigate directly to any PR in the stack
17
17
- Link to Add to Stack, where you can create a new PR that targets the head of the topmost PR
18
18
- Unstack option to dissolve the association between PRs, turning them back into standard PRs
19
19
20
-
20
+
21
21
22
22
## Creating a Stack from the UI
23
23
@@ -37,9 +37,9 @@ When you create the next PR, set its base branch to the first PR's branch. You'l
37
37
38
38
### Step 3: Confirm the stack
39
39
40
-
After creating the PR, you'll see the stack navigator appear in the header, showing both PRs linked together.
40
+
After creating the PR, you'll see the stack map appear in the header, showing both PRs linked together.
41
41
42
-
42
+
43
43
44
44
Repeat this process for each additional PR in the stack — each one targets the branch of the PR before it.
45
45
@@ -101,4 +101,4 @@ To dissolve the stack entirely (turning all Stacked PRs back into independent PR
101
101
102
102
103
103
104
-
After unstacking, each PR retains its current base branch but is no longer linked to the other PRs. The stack navigator and stack-related merge requirements disappear from all affected PRs.
104
+
After unstacking, each PR retains its current base branch but is no longer linked to the other PRs. The stack map and stack-related merge requirements disappear from all affected PRs.
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
@@ -48,14 +48,14 @@ A **stack** is a series of pull requests in the same repository where each PR ta
48
48
GitHub understands stacks end-to-end: the pull request UI shows a **stack map** so reviewers can navigate between layers, branch protection rules are enforced against the **final target branch** (not just the direct base), and CI runs for every PR in the stack as if they were targeting the final branch.
<Imagesrc={stackNavigator}alt="The stack navigator in a pull request header" />
51
+
<Imagesrc={stackNavigator}alt="The stack map in a pull request header" />
52
52
</div>
53
53
54
54
## Working with Stacks
55
55
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 for navigation, focused diffs for each layer, and proper rules enforcement.
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, you can merge all or a part of the stack. Each PR can be merged directly or through the merge queue. **If you want to merge multiple PRs at once (e.g., the bottom two PRs in a stack), simply wait for CI to pass on those specific layers, and you can merge them in a single step.** After a merge, the remaining PRs in the stack 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 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.
Copy file name to clipboardExpand all lines: docs/src/content/docs/introduction/overview.md
+11-4Lines changed: 11 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,7 +40,7 @@ GitHub supports Stacked PRs natively, combining a rich pull request UI with the
40
40
41
41
When a pull request is part of a stack, a **stack map** appears at the top of the PR page. It shows every PR in the stack, their status, and lets you navigate to any layer with one click. This gives reviewers immediate context about where a PR fits in the bigger picture.
42
42
43
-
43
+
44
44
45
45
### Rules and CI Enforcement
46
46
@@ -55,12 +55,19 @@ This ensures that every layer of the stack meets the same quality bar before it
55
55
56
56
### Merging Stacks
57
57
58
-
The entire stack does not need to be merged at once, but PRs must be merged**from the bottom up**. GitHub supports two merge methods:
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:
59
59
60
-
-**Direct merge** — Merges a PR (and all non-merged PRs below it) in a single operation, as long as all conditions are met.
60
+
-**Land the entire stack in one click** by merging the top PR — every PR below it comes with it.
61
+
-**Land part of the stack** by merging a mid-stack PR — the PRs below it come along, and the PRs above stay open.
62
+
63
+
You can't merge a PR while leaving an unmerged PR below it behind. Merging a stacked PR always merges all the unmerged PRs below it as well.
64
+
65
+
GitHub supports two merge methods:
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.
61
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.
62
69
63
-
The resulting commit history is the same as merging each PR individually, starting from the bottom.
70
+
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/webhooks.md
+11-3Lines changed: 11 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,13 +5,13 @@ description: Reference for the stack object in pull_request webhook event payloa
5
5
6
6
When a pull request belongs to a stack, GitHub adds a `stack` property to the `pull_request` object in webhook event payloads. This lets apps and integrations inspect the stack's ultimate target branch — not just the direct parent branch of the PR.
7
7
8
-
The `stack` object is included in the `pull_request` webhook payload for all [pull request lifecycle events](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request).
8
+
The `stack` object is included in the `pull_request` webhook payload for all [pull request lifecycle events](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request) whenever the pull request is part of a stack.
9
9
10
10
11
11
12
12
## The `stack` Object
13
13
14
-
The `stack` object is nested inside the `pull_request` object and contains information about the stack's base branch:
14
+
The `stack` object is nested inside the `pull_request` object. It identifies the stack, describes this PR's place within it, and reports the stack's base branch and ultimate merge target:
15
15
16
16
```json
17
17
{
@@ -24,6 +24,10 @@ The `stack` object is nested inside the `pull_request` object and contains infor
24
24
"sha": "abc123..."
25
25
},
26
26
"stack": {
27
+
"id": 123456,
28
+
"number": 50,
29
+
"size": 5,
30
+
"position": 2,
27
31
"base": {
28
32
"ref": "main",
29
33
"sha": "def456..."
@@ -37,8 +41,12 @@ The `stack` object is nested inside the `pull_request` object and contains infor
37
41
38
42
| Field | Type | Description |
39
43
|-------|------|-------------|
44
+
|`pull_request.stack.id`|`integer`| Global identifier for the stack. |
45
+
|`pull_request.stack.number`|`integer`| The stack's number, scoped to the repository. |
46
+
|`pull_request.stack.size`|`integer`| Total number of pull requests in the stack. |
47
+
|`pull_request.stack.position`|`integer`| 1-based position of this PR within the stack, where `1` is the bottom (the PR closest to the stack's base). |
40
48
|`pull_request.stack.base.ref`|`string`| The branch the entire stack ultimately targets (e.g., `main`). |
41
-
|`pull_request.stack.base.sha`|`string`| The HEAD SHA of that target branch at the time of the event. |
49
+
|`pull_request.stack.base.sha`|`string`| The HEAD SHA of the stack's base branch. |
42
50
43
51
`pull_request.base.ref` is the direct parent branch of an individual PR (the branch below it in the stack), while `pull_request.stack.base.ref` is the ultimate target of the entire stack. These differ for all PRs in the stack except the bottom one.
0 commit comments