GitHub stacked pull requests split a larger change into smaller, dependent pull requests: the first targets a base branch such as main, and each later pull request targets the branch immediately below it. Use a stack when those layers have real dependencies and can benefit from review in sequence; skip it when one cohesive pull request is easier to understand or when the rebasing and merge overhead outweighs the benefit. GitHub currently documents stacked pull requests as a public preview.
What a GitHub pull request stack is—and when it helps
In a stack, each branch builds on the one below it. For example, a schema-change pull request can target main, while an API pull request targets the schema branch and an interface pull request targets the API branch. The lower layer is a prerequisite for the layers above it.
As an Amazon Associate I earn from qualifying purchases.
GitHub describes the goal as breaking large changes into smaller, dependent pull requests that can be reviewed and merged in sequence. That structure can make each diff more focused, but a layer reviewed without the context of the rest of the stack may be harder to assess. See GitHub Docs’ About stacked pull requests.
- Use a stack when work has natural dependencies—for example, shared types or a database schema that other code relies on—and reviewers can evaluate the layers meaningfully.
- Skip a stack when the change is already cohesive, the layers do not make sense on their own, or your team’s review, rebase, and merge overhead exceeds the value of incremental review.
How to create a stack
GitHub documents two approaches: the gh stack extension for GitHub CLI, or pull requests created on the website with each one based on the branch below it. All branches in a stack must be in the same repository; cross-fork stacks are unsupported. GitHub Desktop does not support stacked pull requests. See GitHub’s stack creation documentation.
Using GitHub CLI
Initialize the stack on its trunk, commit the first layer, add a branch for the next logical unit, and repeat. Submit the branches to create and link the pull requests.
gh stack init auth-layer
# Make and commit the first layer
gh stack add api-endpoints
# Make and commit the next layer
gh stack submitThe example follows GitHub’s documented CLI workflow. Add further branches and commits for additional layers before submitting.
Using GitHub’s website
- Create the bottom pull request against the trunk branch, such as
main. - Create the next pull request with the first layer’s branch selected as its base, then choose the option to link it into a stack.
- Repeat for each higher layer, using the immediately preceding branch as the base.
How to update and rebase a stack
Treat each lower branch as a prerequisite for the work above it. If a review comment calls for a change to a lower layer, make the fix there; then update the branches above it. GitHub documents gh stack rebase --upstack to rebase branches above the current one, and gh stack push to push the updated branches. The commands and behavior are described in GitHub’s stack rebasing documentation.
Branches in a stack need a linear history with one another before merging. A change to a lower branch or movement of the trunk can make the history non-linear. GitHub’s gh stack rebase cascades rebases from the bottom upward; resolve any conflicts, then push the updated branches with gh stack push. GitHub documents that this command uses --force-with-lease.
The website also supports a server-side rebase, but GitHub says its generated commits are unsigned. If your team requires signed commits, use the CLI with your local commit-signing configuration.
What protections and checks apply
GitHub evaluates branch protection requirements, required reviews, status checks, CODEOWNERS, and related checks against the stack trunk for each pull request. GitHub Actions workflows configured for pull requests targeting the trunk also run for stack pull requests. Consequently, a pull request partway up the stack can be subject to the same merge requirements as the bottom one. GitHub documents these details in its stack overview.
Rank #4
How merging a stack works
Merge from the bottom upward, either one pull request at a time or as a contiguous group. A higher pull request cannot be merged by itself: merging it brings along any unmerged pull requests below it. When a lower pull request merges, the next pull request is rebased so it targets the trunk directly. See GitHub’s stack merging documentation.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute- Merge queues: GitHub supports merge queues for stacks and queues the pull requests in order. If a pull request is removed from the queue, pull requests above it are removed too.
- Auto-merge: GitHub documents auto-merge as unsupported for stacks.
- API clients: Use the asynchronous merge API. A stack merge may run in the background, so the client must poll for the result.
A practical decision check
- Dependency: Are the upper changes genuinely dependent on lower ones? If not, a single pull request may be simpler.
- Review: Will smaller diffs make the changes easier to review, and can reviewers still understand each layer in the context of the whole?
- Maintenance: Can the team handle cascading rebases, conflict resolution, and branch updates when a lower layer changes?
- Merge workflow: Does the team’s process accommodate bottom-up merging and stack-aware merge queues? If it relies on auto-merge, this workflow does not fit the documented support.
GitHub’s feature documentation identified here was accessed on October 7, 2026, and described stacked pull requests as a public preview. Treat its behavior and interface as documented at that time, rather than as a permanent or generally available guarantee.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
