Preface¶
It’s a pitfall that many teams have fallen into: finishing a large feature all at once and opening a giant Pull Request. Reviewers are daunted by thousands of lines of diffs, CI takes half a day to run, and if anything blocks along the chain, the entire branch branch has to be manually rebased. The idea of Stacked Pull Requests is not new – breaking large changes into a chain of dependent, individually reviewable small PRs – but in the past, it mostly relied on third-party tools like Graphite, Sapling, or maintaining branch baselines yourself.
On July 30, 2026, GitHub announced in its Changelog that Stacked Pull Requests have entered Public Preview, alongside the open-source CLI extension github/gh-stack. Stacked PRs are no longer an “advanced gimmick in the plugin ecosystem”, but a capability built into GitHub’s native PR workflow: the Stack Map UI, one-click merging of the entire stack, and integration with Branch Protection / Merge Queue can all be found in the official documentation. This article is based on GitHub’s official Changelog, documentation, and the gh-stack repository README, to sort out what this feature solves, how to use it, and its relationship with Trunk-based Development.
What are Stacked Pull Requests¶
In the official definition, a Stack is an ordered chain of Pull Requests within the same repository: the bottommost PR uses trunk (usually main) as its base, the next PR uses the lower layer’s branch as its base, and so on. When a reviewer opens any layer, they only see the diff for that layer, not all the files from the entire feature.
A typical three-layer stack structure is as follows:
frontend → PR #3 (base: api-endpoints) ← Stack top
api-endpoints → PR #2 (base: auth-layer)
auth-layer → PR #1 (base: main) ← Stack bottom
─────────────
main (trunk)
This does not conflict with Trunk-based Development: trunk remains the final merge target, and stacked PRs simply split the path “from trunk to the final feature” into several incrementally reviewable layers. Tim Neutkens, head of Next.js, mentioned in the GitHub announcement that the Vercel team used stacked PRs to maintain their large feature delivery pace while reducing the scope of individual reviews.
Limits you need to know in advance (all from official documentation):
- All branches must be in the same repository, cross-fork stacks are not supported.
- GitHub Desktop is not supported yet for stacked PRs.
- Branches within the stack must maintain a fully linear history before merging; when trunk advances or there are new commits on a lower layer branch, cascading rebase is required to restore the chain.
What the July 2026 Public Preview Brings¶
The core change GitHub brought with this public preview is elevating stacked PRs from “CLI-assisted + manually linked on the web” to a first-class citizen of the platform:
1. Stack Map: The stack structure is displayed at the top of the PR page, and reviewers can review different layers in parallel without blocking each other.
2. Branch Protection Evaluated from the Stack Bottom: Regardless of the direct base branch of a PR, Required Reviews, Status Checks, CODEOWNERS, and Code Scanning will all run based on the trunk of the stack. GitHub Actions pull_request events will also trigger based on the bottommost branch of the stack, without needing to modify workflows.
3. One-Click Merge: When merging the stack top (or any ready layer), all unmerged layers below it can be merged atomically together; if only a lower layer is merged, the upper PRs will automatically rebase and retarget.
4. Merge Queue Support: The entire stack can be queued in the correct order; if a layer is removed from the queue, all layers above it will also be removed at the same time. The merge group capacity of the Merge Queue allows up to a 50% excess over the configured limit to keep the entire stack merged in the same batch as much as possible.
5. All Three Merge Methods Available: Merge Commit, Squash, and Rebase, with the entire set of PRs landing as a single atomic operation.
Public preview rollout schedule: it will be gradually rolled out to all repositories in the coming days; Merge Queue support for stacked PRs will be rolled out in batches over the coming weeks.
Installing the gh stack CLI¶
The local development workflow recommends installing the official CLI extension. The prerequisite is GitHub CLI v2.0 or above.
gh extension install github/gh-stack
github/gh-stack is licensed under the MIT License, the repository was created in February 2026, and had earned hundreds of stars on GitHub as of the public preview announcement. Stack metadata is saved locally in .git/gh-stack (JSON, will not be committed to the repository); gh stack init will automatically enable git rerere to reuse resolved conflicts during repeated rebases.
If you use GitHub Copilot or other AI Agents, you can also install the supporting skill to let the Agent familiarize itself with the stacked PR workflow:
gh skill install github/gh-stack
You can also do this without installing the CLI: the underlying Git operations are standard procedures, and you can create stacks directly on github.com or the GitHub mobile app; tools like Jujutsu and Sapling can also use gh stack or the web interface to create stacks after pushing branches.
Quick Start: From init to submit¶
Below is a minimal usable workflow, with commands from the gh-stack official README.
1. Initialize the stack and add layers¶
# Interactively create the first layer of the stack
gh stack init
# Continue adding layers on top of the current layer
gh stack add api-endpoints
# Add one more layer
gh stack add frontend
You can also specify multiple branches at once, or specify a non-main trunk:
gh stack init --base develop feature-auth feature-api feature-ui
gh stack add supports -m for commit messages, and -A/-u to stage changes before creating a branch, which fits the rhythm of “finish one layer and immediately start the next”.
2. Push and create linked PRs¶
gh stack push
gh stack view
gh stack submit
gh stack submit will create a PR for each branch in the stack, automatically set the base to the next layer’s branch, and establish a Stack association on GitHub. Adding --auto skips the interactive editor, which is suitable for scripting scenarios.
3. Sync after changes to lower layers¶
After a reviewer requests changes to the bottom PR, you need to cascade the changes to the upper layers:
gh stack rebase
gh stack push
You can also click Rebase stack in the Merge area on the web, and the server will perform the cascading rebase.
gh stack sync is used for daily maintenance such as syncing remote status and cleaning up merged branches.
4. Merge¶
After all layers in the stack meet the Branch Protection requirements and the lower layers are also ready, you can merge the entire stack with one click on the GitHub webpage, or use:
gh stack merge
Before merging, the official requirement is that the target layer and all layers below it have passed reviews and CI, and the stack history remains linear.
Cooperation with Merge Queue and Code Review¶
For teams that have enabled Merge Queue, the value of stacked PRs is summed up by John Resig in the announcement: sending multiple layers of PRs to the Merge Queue for merging in one go, eliminating the friction of queuing layer by layer and manually rebasing bases.
On the review side, TED CTO Andy Merryman pointed out: After AI improves development output, PR size has become a new bottleneck; stacked PRs split reviews into smaller, dependent logical blocks, making feedback loops shorter. WHOOP engineer Mayank Saini emphasized that after one-click merging of the entire stack, the experience “feels like a native GitHub feature, not an external tool”.
In practice, you can follow several officially implied best practices:
- Each layer focuses on a single concern: Split schema changes, APIs, and UI into separate stacks, so reviewers can view different layers in parallel based on their expertise.
- Keep stack depth controllable: Merge Queue may split oversized stacks into multiple merge groups, and too many layers will increase coordination costs.
- CI optimization: Workflows can read stack metadata via github.event.pull_request.stack to avoid running full integration tests repeatedly for each layer (see the official “Optimizing CI for stacked pull requests” documentation for details).
Relationship with Third-Party Stacking Tools¶
Graphite, Sapling, Jujutsu and others have their own advantages in local branch management; after GitHub’s public preview, the platform-side Stack UI, protection evaluation, and Merge Queue integration are now handled officially, and third-party tools can still handle local workflows before connecting with gh stack submit or the web interface.
If your team is already accustomed to small commits under Trunk-based Development, stacked PRs are equivalent to mapping “small steps” into “a chain of small PRs”, with trunk always being the final destination; if you are still used to long-lived feature branches, you can start with a pilot stack of no more than three layers, familiarize yourself with the rebase and protection rules before scaling up.
Summary¶
Starting July 30, 2026, GitHub Stacked Pull Requests is rolling out to all repositories in public preview, and you can complete stack creation, rebase, PR creation, and merging in the terminal with gh extension install github/gh-stack. It targets the old problem of “large PRs being hard to review, multi-branch rebase hell”, bringing the stacked development model into GitHub’s native PR, Checks, and Merge Queue system.
The feature is still in Public Preview, and APIs and behavior may change; more details can be found in the Stacked pull requests documentation, and feedback can be submitted to the official GitHub stacks discussion.