GitHub put stacked pull requests into public preview on 30 July 2026. In practice that means one extension, six commands, and a merge model where you land the bottom of the stack and everything above it retargets itself. The install is gh extension install github/gh-stack, and the sequence for a first stack is gh stack init, gh stack add, gh stack push, gh stack submit. Before you rewrite your workflow around it, two restrictions matter more than any of the commands: every branch has to live in the same repository, so cross-fork stacks are not supported, and auto-merge does not work on a stack.
What the feature is for
GitHub describes a stack as "an ordered series of pull requests that each represent focused layers of your change", and the documentation frames the job as breaking a large change into "a chain of smaller, dependent pull requests you can review and merge independently". The problem it addresses is familiar: a 900-line pull request sits for three days because no reviewer has an hour, and while it sits you start the follow-up work on a branch cut from the unmerged one, then maintain that relationship by hand every time the base moves.
Each pull request in a stack shows only its own layer's diff, carries a stack map showing where it sits, and can be reviewed and approved on its own. Different people can review different layers at the same time. That is the entire pitch, and it is a direct answer to the constraint we wrote about in review capacity being the new limit: if an assistant helps you produce changes faster than a human can read them, the lever left is making each unit smaller.
The sequence, from empty repo to merged
You need GitHub CLI 2.90.0 or later and Git 2.20 or later, and you need to be authenticated with gh auth login.
gh extension install github/gh-stack. If you drive work through a coding agent,gh skill install github/gh-stackinstalls the matching skill.gh stack init. This sets up tracking and creates your first branch, targeting the repository default branch.- Do the first layer of work and commit it. Keep it to one idea: the schema change, or the API surface, or the UI.
gh stack add second-layerfor the next branch. If you have uncommitted work in progress,gh stack add -Am "add rate limiting"stages, commits and creates the branch in one step.- Repeat step 4 for as many layers as the change needs. The docs state no maximum, and none is published, so treat the ceiling as unknown rather than infinite.
gh stack pushto push every branch.gh stack submitto open the pull requests. They are linked in order automatically: the first targets your default branch, and each later branch targets the one below it.gh stack viewat any point prints the branches, the pull request links, their statuses and recent commits. This is the command you will actually use daily.
Merging is bottom-up, and that is not a preference
The rule from GitHub's merge documentation: "you cannot merge a mid-stack pull request in isolation." Stacks merge from the bottom, meaning the layer closest to the trunk. When you select a pull request to merge, it "and all unmerged pull requests below it land on the base branch together as a single operation". So picking the third layer merges one, two and three at once, as one unit.
After a merge, the next unmerged pull request is automatically rebased to target the stack base directly. It becomes the new bottom, ready to review and merge on its own. That retargeting is the manual chore the feature removes.
Four preconditions apply before anything merges: the pull requests below must be approved with passing checks, the stack must have linear history, the current pull request must satisfy branch protection, and you cannot lean on auto-merge, which is not supported for stacks. Merge queues are supported, with the whole stack entering in order, and one sharp edge: if a pull request is removed or ejected from the queue, everything above it in the stack is ejected too. GitHub says merge queue support is rolling out progressively over the weeks after the preview.
Five things that break a stack, and the command that fixes each
| What happens | Effect | Recovery |
|---|---|---|
| Rebase conflict while cascading | The rebase halts and lists the affected files | Resolve, then gh stack rebase --continue, or gh stack rebase --abort to restore branches to their pre-rebase state |
| Conflict during a sync | gh stack sync restores every branch to its original state rather than applying a partial update | Resolve the underlying conflict, then sync again |
| Someone closes a middle pull request | Everything above it becomes unmergeable | Reopen it, or restructure the stack so the layers above target a live base |
| History goes non-linear | The stack refuses to merge; caused by pushing to a lower branch or the trunk moving ahead | gh stack rebase && gh stack push |
| A queued pull request is ejected | Every pull request above it is removed from the queue too | Fix the failing check, requeue from the bottom |
Two more commands exist for interrupted edits: gh stack modify --continue after you resolve staged conflicts, and gh stack modify --abort to restore the pre-modify snapshot. Learn those four abort and continue commands before your first real stack. The failure mode with any stacking tool is discovering mid-conflict that you do not know how to get back to a known state.
The cross-fork gap
The line that deserves more attention than it is getting sits in the troubleshooting page: "Stacked pull requests require all branches to be in the same repository. Cross-fork stacks are not supported."
That excludes the single most common open source contribution shape. If you fork a project, branch in your fork and open a pull request upstream, you cannot stack. The feature is aimed at teams with push access to one repository, not at outside contributors, which is precisely the population that most needs a way to break a large contribution into reviewable pieces for a maintainer who owes them nothing. Worth knowing before you promise a maintainer a stacked series.
When a change is worth stacking
Three conditions, all of which have to hold. There are three or more genuinely separable layers, so a schema migration, then the service change, then the interface, rather than one change you have sliced arbitrarily. Everyone involved can push to the same repository. And the later layers are worth writing before the earlier ones merge, which is the actual value: you keep working instead of waiting.
If a change is two commits, open two ordinary pull requests and skip the tooling. If the layers are not separable, stacking produces pull requests that cannot be understood alone, which costs your reviewers more attention than one honest large diff. And the feature is in public preview and described as subject to change, so keep the fallback in mind: a stack is only branches and base pointers, and you can always retarget them by hand.
The habit this rewards is the one worth adopting whether or not you install the extension, and it fits the argument for boring, well-understood tooling we made in the boring stack: decide the layers before you write the code, not after the diff has grown to 900 lines. If your work is agent-assisted, that decision is also the point where you can still say which layer you actually reviewed, which matters for the reasons set out in where your code actually goes.
Discussion
Sign in with Google or just a name. No email link, no password to remember.