A stack is a chain of pull requests in one repository: the bottom layer targets the trunk (usually the default branch) and each layer above targets the branch of the layer below. Only a native stack, one GitHub records as a stack, behaves as one. A PR that only targets another PR's branch is not a stack layer: merging it lands that PR alone, into that branch.
This file is the single source for when to stack. Skills that plan, split or open pull requests point here instead of restating it.
Stack when the next pull request builds on one that has not merged yet:
- Dependent changes: the upper change cannot build, test or be reviewed without the lower one (a shared type, then its callers; an API, then its UI).
- A large change split for review: one change too big to review whole, cut into layers that each review on their own.
- An ordered series: parts that must land in order, such as a "part N of M" series or items joined by blocked-by edges, including parts that edit the same file and would otherwise conflict. A stack lets part N+1 start while part N is still in review instead of after it merges.
Do not stack independent changes. Each one is its own PR off the trunk, so it can merge, revert or stall without touching the others; stacking them only adds rebases and ties their landings together.
A stack saves the wait for the lower merge, not CI time. Every layer runs its own checks and review lanes, and each restack re-runs them on the layers above the change. Keep stacks short, and fix a lower layer before the upper layers collect review.
Check the repository's pipeline first. A pipeline can refuse a layer whose base is not the default branch: a trust gate that fails it, a lane that skips it, an auto-merge sweep that reads only PRs into the default branch, or done-evidence that counts only merges into it. Where any of those gates a required check, an upper layer cannot go green, so use sequential PRs off the trunk until the pipeline accepts layers. Read the consuming project's PR pipeline docs before stacking. In this marketplace the review and run lanes accept a native stack layer whose stack base is the default branch, and still fail any other non-default base (pr-run-activity.md, "The run job"; #15400). The merge and issue lanes do not handle layers yet (#15410), so an attended session may stack, and an unattended lane does not stack until that work lands.
- Pointer: for why and when GitHub recommends a stack, fetch About stacked pull requests live; for how workflows see a layer's base, fetch Optimizing CI for stacked pull requests: How workflows run for a stack. Correlate with the probe results in the pull request that closed #7664.
- Recheck trigger: #15410 closes.
-
Build the stack with GitHub's
gh stackextension (github/gh-stack). Read its commands from the CLI reference below rather than from memory. -
Put each dependency in the same layer or a lower one, never a higher one.
-
Each layer is a pull request in its own right: open it with
/source-control:pull-request create, take it throughreadyandmonitor, and hold its title and body to the same contract as any other PR. -
Inside a linked worktree (
/source-control:worktree), use an extension release that tracks stacks per repository, and the Git floor the CLI reference names. Unattended lanes setGH_STACK_NO_UPDATE_NOTIFIER=1to keep its upgrade notice out of their output. -
After pushing to a lower layer, restack the layers above yourself (
gh stack rebase, thengh stack push). -
Pointer: when you need a command, the worktree requirements or the environment switches, fetch Stacked PRs CLI commands live; correlate with the gh-stack v0.2.0 release notes for per-repository tracking.
-
Merging a layer lands it and every open layer below it, all or nothing. Run the Phase 4.1 readiness re-verification (pull-request merge.md) on every layer that will land, not only the one you merge, and get the user's approval for the whole set.
-
Merge with the extension's merge command or the async merge API (pull-request merge.md §4.2). The synchronous REST merge endpoint does not support stacks.
-
The trunk's rules govern every layer, and GitHub evaluates them when the merge runs, not when it is requested; a stack merge cannot bypass them.
-
After a partial merge, expect the layers above to re-run their checks and review lanes on their new head before they are ready again.
-
Treat a stack as merging until every one of its PRs reads
MERGED; on a trunk with a merge queue, read how the queue takes the stack from the pointer below, live. -
/source-control:babysit-prsholds stack layers for a human unless itsbabysit_stacked_prsoption is on. -
Pointer: when you need how a stack merges, its rules and CI, or its merge methods, fetch About stacked pull requests: Rules, CI, and merging live; for how a merge queue takes a stack, Merging stacked pull requests: Merging using a merge queue; for the merge command, Stacked PRs CLI commands: gh stack merge; for the synchronous endpoint's limit, Merge a pull request. Correlate with the general availability changelog and with the queue probe in the pull request that closed #7664.