A large feature does not have to arrive as one giant pull request. GitHub stacked pull requests let you split dependent work into a chain of smaller PRs, so each layer can be reviewed on its own while the full change is still visible.
The useful idea is simple: the first branch targets your trunk, the next branch targets the first branch, and the next branch targets the second. Each PR shows the delta for one layer instead of repeating everything that came before it. GitHub describes this as a stack, and the current stack model is documented in its [stacked PR overview].
What a stacked pull request looks like
Imagine you are adding an account settings area. The work has three natural boundaries: data model, API routes, and interface. A stack can represent those dependencies without waiting for the whole feature to be finished.
main
└── auth-layer → PR 1 targets main
└── api-routes → PR 2 targets auth-layer
└── settings-ui → PR 3 targets api-routesThe bottom PR is closest to the trunk. The top PR is the furthest away. Reviewers can start with the first layer for the full story, or open one layer directly when they only need to check a specific concern.
Why stack a change instead of opening one large PR?
Stacking is most useful when the work has real dependency boundaries. It is not a reason to split one small change into five PRs. If the layers cannot be explained in one sentence each, the stack probably needs a simpler shape.
GitHub support is new, so check the availability first
GitHub’s current stacked PR feature is in private preview. The official [GitHub Stacked PRs project] explains that the feature must be enabled for your repository, and the companion [gh stack repository] documents the waitlist and CLI workflow. Treat this as preview functionality, not a generally available team policy.
The underlying model still follows ordinary Git branches and pull requests. The stack fields are also exposed in GitHub’s [Pull request GraphQL reference], including the stack size, base branch, and position of each entry.
A practical CLI workflow
If your repository has access to the preview, the official CLI extension handles the branch relationships and the repetitive push and rebase work. The [quick start guide] uses this shape:
gh extension install github/gh-stack
gh stack init
# make the first layer
gh stack add api-routes
# make the second layer
gh stack add settings-ui
# make the third layer
gh stack push
gh stack submitThe local stack metadata lives under .git, so it is not another file that your team has to merge. The important shared state remains the branches and pull requests on GitHub.
How to choose layer boundaries
A useful layer has a small answer to the question “what changed here?” Good boundaries often follow one of these lines:
Avoid layers that are only split by file type. “All TypeScript files” and “all CSS files” are usually weaker boundaries than “add the API contract” and “render the new settings state.” Review follows behavior, not directory structure.
Review the stack from the bottom up
Start at the lowest unmerged PR when you need the complete story. That keeps the base assumptions clear. For a focused review, open the layer that owns the concern and use the stack map to move to adjacent PRs. GitHub’s practical [stack review guide] recommends this order because each PR shows only its own layer.
When feedback changes a lower layer, expect the branches above it to need a cascading rebase. That is the main operational cost of stacking. The CLI can help with it, but the team still needs to agree on who rebases and when.
How merging works
You can merge the bottom PR alone, or merge a higher PR to land that PR and the unmerged layers below it. The stack cannot skip an unmerged dependency in the middle. If you land only part of the stack, the remaining layers are retargeted and rebased so the next unmerged PR can continue from the trunk.
Before adopting stacks, check your branch protections, required checks, CODEOWNERS rules, and merge queue behavior. The preview documentation says protections are evaluated against the final target branch, but your repository’s actual rules still decide whether a stack can move.
When stacked PRs are the wrong tool
A small adoption checklist
Stacked pull requests are not a replacement for good design or clear review notes. They are a way to keep dependent work moving while giving reviewers smaller, more honest diffs. Start with one feature that has obvious layers, measure the review experience, and keep the workflow only if it makes the change easier to understand.