For developers and reviewers who already know ordinary pull requests. Read the first two bites, then expand the others as needed. Each section can also be shared separately.
Checked against GitHub's documentation on 2 October 2026. The feature is in public preview, so details can change. GitHub overview
A stack is a chain of dependent PRs. The bottom PR targets a trunk such as main; each higher PR targets the branch below it. Each PR shows its own layer's diff. GitHub overview
Imagine adding saved searches:
main
└── saved-search-model PR #101 → main
└── saved-search-api PR #102 → saved-search-model
└── saved-search-ui
PR #103 → saved-search-api
Our example has three review questions:
- Is the storage model sound?
- Does the API use that model correctly?
- Does the UI use that API correctly?
The author can keep building while earlier layers await review. Dependencies must live in the same layer or below it. GitHub overview
Pause here: Why does #102 target the model branch? Because that is the code it builds on.
In our example, the API branch contains the model changes too. But comparing it with the model branch isolates the API addition. Comparing it with main would mix both concerns.
GitHub provides a stack map in the merge box and a layer indicator on each PR. Every layer inherits merge requirements from the stack's trunk, including required reviews and checks. Default-branch PR workflows also run for higher layers. GitHub overview
Suggested review habit:
- Start with the lowest layer to understand the foundations.
- Judge the current layer's change, using lower layers as context.
- Put feedback on the PR that owns the code needing correction.
- Read the selected merge scope before clicking Merge.
Pause here: You can review #103 before #101 merges. That does not make #103 independently mergeable.
Bite 3 — Create your first stack
Use GitHub CLI 2.90.0 or later, Git 2.20 or later, and a repository you can push to. These are the quickstart's prerequisites; the command reference currently lists a lower CLI minimum, so use the quickstart's stricter version. GitHub quickstart, command reference
gh auth login
gh extension install github/gh-stackRun these inside your repository. Substitute real file paths for the placeholders.
# Start the bottom layer, explicitly choosing main as the trunk.
gh stack init --base main saved-search-model
# Implement and test the model, then commit its files.
git add <model-files>
git commit -m "Add saved search model"
# Create and switch to the next layer.
gh stack add saved-search-api
# Implement and test the API, then commit its files.
git add <api-files>
git commit -m "Add saved search API"
# Create and switch to the top layer.
gh stack add saved-search-ui
# Implement and test the UI, then commit its files.
git add <ui-files>
git commit -m "Add saved search UI"
# Publish the branches and create linked PRs.
gh stack submit
gh stack viewsubmit pushes the branches and creates the PRs with their chained bases. Its interactive editor lets you set descriptions and draft status. A separate gh stack push first is optional. GitHub quickstart, command reference
Suggested description for #102:
Adds endpoints for creating and listing saved searches.
Depends on the storage model in #101. The UI follows in #103.
Review this layer for endpoint behavior, validation, and authorization.
Validation: [describe the tests actually run]Bite 4 — Respond to feedback in a lower layer
Suppose review finds a model bug while you are working on the UI. Correct it on the model branch, then propagate it upward:
# Commit or otherwise preserve current work before switching.
gh stack checkout saved-search-model
# Fix and test the model.
git add <changed-files>
git commit -m "Correct saved search validation"
gh stack rebase --upstack
gh stack push
gh stack topA cascading rebase refreshes dependent branches in order. If conflicts occur, resolve and stage them, then run gh stack rebase --continue; use gh stack rebase --abort to restore the stack's previous state. Managing stacks
After rebasing, rerun the relevant tests: the API and UI now rest on changed foundations.
GitHub also offers a server-side rebase, but its generated commits are unsigned. Repositories requiring signatures should use the CLI with local Git signing configured. Managing stacks
Bite 5 — Merge from the bottom upward
Choosing a PR merges it and every unmerged PR below it. Merging stacks
| Select in our example | Merge scope | Remains open |
|---|---|---|
| #101 | Model | API and UI |
| #102 | Model and API | UI |
| #103 | Model, API, and UI | Nothing |
You cannot land #102 alone while #101 remains unmerged. The selected layer must satisfy the trunk's protection requirements; lower layers need approval and passing checks, and the stack must be linear. GitHub rebases the next remaining PR onto the trunk after merging. Auto-merge is currently unsupported. Merging stacks
Merge queues are supported, but a stack may land across consecutive queue groups. If a layer is ejected, layers above it leave the queue too. Merging stacks
Then refresh local state:
gh stack sync
# Optionally delete local branches for merged PRs:
gh stack sync --pruneBite 6 — Pick useful boundaries
The following are suggested team practices:
- Start with two or three layers on a real feature.
- Give each layer one clear purpose and include tests for that purpose.
- Keep lower layers safe to ship: merging them can expose them before the rest lands. Use feature flags or compatibility changes where needed.
- Prefer independent PRs when changes have no dependency.
- Agree who owns stack maintenance, especially when several people edit its branches.
A useful question is: “Could I explain what this layer changes and how I tested it in a short paragraph?” If that is difficult, reconsider the boundary.
Stacks require one linear chain in one repository. Fork-based contributions and branching dependency graphs do not fit the current feature. GitHub says no feature enablement is required. Organization rollout guide
Bite 7 — Commands and limitations to remember
| Command | Purpose |
|---|---|
gh stack view |
Inspect the stack |
gh stack switch |
Choose a layer interactively |
gh stack checkout <PR-number> |
Fetch/check out a stack through a PR |
gh stack rebase |
Rebase the stack in dependency order |
gh stack push |
Push branches without creating PRs |
gh stack submit |
Push and create/update PRs and their stack |
gh stack sync |
Fetch, reconcile, rebase where needed, push, and refresh state |
gh stack modify |
Restructure the stack interactively |
sync does not create missing PRs. After changing a lower layer, use the explicit rebase workflow in Bite 4. submit --auto creates new PRs as drafts unless --open is supplied. Command reference
Further limitations:
- GitHub Desktop does not support stacks. GitHub overview
- Once all layers merge, the stack is complete; later work starts a new stack. Merging stacks
- Merge bots must use GitHub's asynchronous merge API for stacks; legacy merge endpoints cannot merge them. Organization rollout guide
Try a two-layer change: a helper with tests, followed by a caller that uses it. Publish both, request a helper correction, propagate that correction, then merge the helper first. Check the remaining PR's base and diff, and sync locally.
That exercises the complete cycle: split → build → review → propagate → merge → sync.