iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
GitHub stacked pull requests split a larger change into a same-repository chain of dependent pull requests: the first targets a trunk such as main, and each later pull request targets the branch immediately below it. Use a stack when those dependencies make incremental review useful; skip it when one cohesive pull request is easier to understand and maintain. GitHub documents stacked pull requests as a public-preview feature, so its behavior and interface may change.
What is a GitHub stacked pull request?
A stack is a sequence of branches and pull requests in which each layer builds on the one below it. For example, a database-schema pull request might target main, while an API pull request targets the schema branch, and an application pull request targets the API branch. Each pull request can focus on one layer, but the upper layers depend on the lower ones.
GitHub Docs describes the goal as breaking large code changes into a chain of smaller, dependent pull requests that can be reviewed and merged independently. “Independently” does not mean an upper pull request can be merged alone: merging a higher layer also brings in the unmerged layers beneath it. GitHub Docs: About stacked pull requests
When should you use a stack—and when should you skip it?
| Use a stack when… | Skip a stack when… |
|---|---|
| A large change has real dependencies and can be divided into useful review layers, such as shared types followed by code that depends on them. | The work is already cohesive and can be reviewed clearly as one pull request. |
| Reviewers benefit from examining focused diffs in sequence. | The layers make little sense without the full change, so reviewing them separately risks missing important context. |
| Your team can accommodate cascading rebases, conflict resolution, branch updates, and bottom-up merging. | The maintenance and merge overhead outweighs the benefit of incremental review. |
A stack changes how work is organized; it does not automatically make review better. Reviewers still need enough context to understand how a layer fits into the complete change. GitHub specifically cautions that reviewing a layer without the rest of its stack can reduce review quality. GitHub Docs: About stacked pull requests
#1 Best Overall
How do you create a stack?
GitHub documents two ways to create one: use the gh stack extension with GitHub CLI, or create linked pull requests on GitHub’s website. All branches in a stack must be in the same repository; cross-fork stacks are not supported. GitHub Desktop does not support stacked pull requests. GitHub Docs: About stacked pull requests
Option 1: Build and submit it with GitHub CLI
Install and configure the gh stack extension as described in GitHub’s instructions. Start the stack on its trunk, commit the first layer, add a branch for each next logical unit, and submit the branches to create and link their 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 submitHere, auth-layer is the first branch, and api-endpoints is a dependent layer above it. Continue adding and committing branches before you submit the stack. See GitHub Docs: Creating a stack for the documented CLI workflow.
Option 2: Create linked pull requests on GitHub.com
- Create the bottom pull request with the trunk branch, such as
main, as its base. - Create the next pull request with the branch for the first layer as its base, rather than the trunk.
- Choose the option to link that pull request into a stack.
- Repeat for each dependent branch, basing each new pull request on the layer directly below it.
For the website workflow and its current interface, see GitHub Docs: Creating a stack.
Rank #3
How do you update a stack after review or trunk changes?
Treat lower branches as prerequisites and upper branches as dependent work. If feedback calls for a change to a lower layer, make the fix on that layer, then update the branches above it. GitHub documents gh stack rebase --upstack to rebase branches above the current one, followed by gh stack push to push the updated branches. GitHub Docs: Rebasing a stack
A stack needs linear history between its branches before it can merge. A change to a lower branch—or movement of the trunk—can make the stack non-linear. The CLI’s gh stack rebase rebases the stack from the bottom up; resolve any conflicts, then use gh stack push to publish the updated branches. GitHub says this push uses --force-with-lease. GitHub Docs: Rebasing a stack
You can also rebase a stack on GitHub’s website. GitHub documents that commits generated by a server-side rebase are unsigned. If your team requires signed commits, use the CLI with your local signing configuration.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteHow do checks and branch protection apply?
For each pull request in a stack, GitHub evaluates branch-protection requirements, required reviews, status checks, CODEOWNERS, and related checks against the stack trunk. GitHub Actions workflows configured for pull requests targeting the trunk also run for stack pull requests. A middle layer can therefore face the same merge requirements as the bottom pull request; it is not exempt simply because it targets another stack branch. GitHub Docs: Merging a stack
Best Value
How do you merge a stack?
Merge from the bottom up, either one pull request at a time or in a contiguous group. You cannot merge a higher pull request in isolation: merging it brings along all unmerged pull requests below it. When a lower pull request merges, the next pull request is rebased so that it targets the trunk directly. GitHub Docs: Merging a stack
- 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 as well.
- Auto-merge: Auto-merge is not supported for stacks.
- API clients: Use the asynchronous merge API. A stack merge may run in the background, so poll for its result rather than assuming the request has completed.
These behaviors are documented in GitHub Docs: Merging a stack.
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.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
