GitHub Now Supports Stacked Pull Requests Natively

03 August 2026 at 10:15~ 7 min read

#devops #github #software engineering #tools

GitHub added native stacked pull requests in public preview on 30 July 2026. A large change can now be split into several dependent pull requests while GitHub keeps their order, reviews, checks and merge state connected.

The idea is not new. Teams have built stacks with ordinary Git branches or tools such as Graphite and Sapling for years. GitHub’s change matters because the stack is now a platform object: reviewers can see it in the pull request, branch protection applies to every layer and GitHub can merge several layers as one operation.

It is worth trying on changes that have a real dependency order. It is not a reason to turn every feature into six pull requests.

What is a stacked pull request?

A stack is a linear chain of at least two pull requests in the same repository. The bottom pull request targets the trunk branch, usually main. Every pull request above it targets the branch immediately below.

For an authentication feature, the stack might look like this:

main
└── auth-schema   → PR #101, base: main
    └── auth-api  → PR #102, base: auth-schema
        └── auth-ui → PR #103, base: auth-api

Each pull request shows only the work added by its layer. The API reviewer does not need to work through the schema diff again, and the UI reviewer can start before either lower layer has merged.

The order also records a constraint. auth-ui depends on auth-api, which depends on auth-schema. A change belongs in the same layer as its dependency, or somewhere below it. Unrelated work should remain a separate branch and pull request.

Why use a stack instead of one large pull request?

The main benefit is review size. A 1,500-line feature might contain a migration, domain logic, an API and a client change. Those are easier to understand as four focused diffs than as one pull request in which every concern arrives at once.

Ordinary pull requests make that split awkward when later work depends on an earlier change that is still being reviewed. You can create branches from branches manually, but then reviewers have little visibility of the chain and the author has to keep rebasing each branch above every changed layer.

GitHub now handles the parts that made this workflow brittle:

a stack map shows the complete chain and the status of each pull request
reviews can happen on separate layers in parallel
a cascading rebase updates the branches above a changed or merged layer
rules and checks from the stack’s trunk apply to every pull request
merging a higher layer can also merge every ready layer below it

The pull requests remain separate review units. The stack supplies the dependency information and the operations that need to understand it.

Create a stack with `gh stack`

GitHub supports stacks on the website, GitHub Mobile, through its APIs and with an official GitHub CLI extension. The CLI is the most complete authoring workflow.

GitHub’s current quickstart requires GitHub CLI 2.90.0 or later and Git 2.20 or later. Install the extension from a repository you can push to:

gh auth login
gh extension install github/gh-stack

Initialise the first branch, then work on it as normal:

gh stack init auth-schema

# Edit the schema files.
git add .
git commit -m "Add passkey credential schema"

When the next piece depends on that work, add another layer. The command creates and checks out a branch at the current HEAD:

gh stack add auth-api

# Add the API implementation.
git add .
git commit -m "Add passkey registration endpoint"

gh stack add auth-ui

# Add the client flow.
git add .
git commit -m "Add passkey registration UI"

Submit the stack when the layers are ready for review:

gh stack submit

submit pushes the branches, creates a pull request for each branch and links them as a stack on GitHub. Its interactive editor lets you set each title and description and choose whether a layer opens as a draft.

You can inspect the order and pull request state from the terminal at any time:

gh stack view

The resulting pull request bases are the important part: auth-schema targets main, auth-api targets auth-schema, and auth-ui targets auth-api. That is why each review contains only its own layer.

Updating a lower layer

Review often finds a problem near the bottom of a stack. Move to that branch, make the correction, then synchronise the stack:

gh stack bottom

# Apply the review feedback.
git add .
git commit -m "Validate passkey credential IDs"

gh stack sync

gh stack sync fetches remote changes, rebases dependent branches when necessary, pushes them and updates the pull request state. If the rebase needs manual conflict resolution, use gh stack rebase, resolve and stage the files, then continue with gh stack rebase --continue.

This is still Git history. Changing a foundational layer changes the commits above it, so a large or frequently edited bottom pull request can create repeated review work across the stack. Keep lower layers small and settle their interfaces early where possible.

Checks and branch protection apply to every layer

Without native support, a workflow configured for pull requests targeting main may run only for the bottom branch. GitHub evaluates every stacked pull request against the bottom pull request’s base instead.

That means required reviews, CODEOWNERS, status checks and GitHub Actions workflows targeting main apply to mid-stack and top-stack pull requests too. A layer cannot avoid the trunk’s rules merely because its immediate base is another feature branch.

There is a cost: CI runs once for each pull request in the stack. A five-layer stack can therefore run an expensive integration suite five times. GitHub exposes stack metadata through github.event.pull_request.stack, which lets mature pipelines skip jobs that genuinely add no evidence on some layers. Start by measuring the duplication rather than disabling checks speculatively.

Merging works from the bottom up

The dependency order controls the merge order. You can merge:

the bottom pull request on its own
a middle pull request and every unmerged layer below it
the top pull request and the complete ready stack

If you merge part of the stack, higher pull requests remain open. GitHub rebases and retargets them to the stack’s trunk. Merge commits, squash merges and rebase merges are supported, and GitHub says the resulting history matches merging the pull requests individually from the bottom upwards.

Stacks also work with merge queues, although GitHub is rolling that support out progressively during the preview. Existing protections still have to pass for each layer. With a merge queue, the selected pull requests enter the queue together but may land in separate queue groups.

Current public preview limits

“Native” does not yet mean universal or finished. The feature is in public preview and GitHub says it is subject to change.

The main limits are:

every branch must be in the same repository, so pull requests from forks cannot join a stack
stacks must be linear; they cannot represent a dependency tree with two parallel branches
GitHub Desktop does not support stacks
reordering a stack requires gh stack modify; it cannot be done on the website
a fully merged stack is closed and cannot be extended
tools that merge pull requests through the API must use GitHub’s new stack merge API

The last point deserves attention before a team-wide rollout. Bots, ChatOps commands and internal release tools may correctly read a stacked pull request but fail when they try to merge it with the legacy pull request endpoint.

Where stacks fit

Use a stack when a change has distinct review boundaries and a genuine dependency chain: a schema before a model, a model before an endpoint, or an internal API before its callers.

Avoid one when the changes can merge independently. Independent pull requests are easier to schedule, revert and release. A stack makes the dependency explicit; it should not create a dependency that the code does not need.

For a first trial, choose a feature that naturally splits into two or three layers. Confirm that CI, required reviews and your merge automation behave as expected before using longer stacks. The best sign that the workflow is helping is not the number of pull requests. It is that each reviewer can understand one layer without reconstructing the entire change.