Every developer knows the feeling: you push a branch with three weeks of work in it, open a pull request, and the review comes back with one comment. “This is too big. Can you split it?” Then you spend an afternoon untangling commits you wrote in a blur of context switching, trying to remember what each file was even for.
I hit that wall a lot in my team. We review each other’s code religiously, but big PRs make honest review impossible. Nobody wants to hold up the whole feature over a style nit in file twelve of twenty. So the nits get skipped, the risky stuff gets rubber-stamped, and the “review” becomes a formality nobody feels good about.
GitHub just moved its answer to this problem — stacked pull requests — into public preview on July 30, 2026, and the tooling is genuinely good. I’ve been testing the gh stack extension for the last few days, and it’s the first workflow tool in a while that made me want to change how I work. Here’s how to use it, step by step — the commands below all come from the official gh-stack repository and the GitHub quickstart, so they should survive contact with your actual terminal.
What Are Stacked PRs, Anyway?
A stacked PR splits one large change into a chain of small pull requests that build on each other. Instead of one branch carrying an entire feature, you get a stack of branches, each one sitting on top of the previous layer:
frontend → PR #3 (base: api-endpoints) ← top
api-endpoints → PR #2 (base: auth-layer)
auth-layer → PR #1 (base: main) ← bottom
─────────────
main (trunk)
The bottom of the stack sits on the trunk branch — usually main — and every layer above it bases itself on the branch below. Each pull request shows only the diff for its own layer. Reviewers see one focused change at a time, and you merge the whole feature as one unit when everything passes.
This is the model tools like Graphite have pushed for years. The difference is that GitHub now owns it natively — no third-party SaaS, no extra account, no custom merge flow that fights the platform.
Why This Matters Right Now
Stacked PRs matter more in 2026 than they did five years ago, and the reason is sitting in your editor right now: AI coding agents generate a lot of code, very fast. If your assistant spits out a full feature across twenty files, you can’t review it in one pass — and you shouldn’t have to. Small, layered diffs are the only realistic way to keep review quality high when the volume of code goes up.
It’s also a natural fit for the way I’ve been thinking about review since I wrote my piece on reviewing AI-generated code like a senior engineer. The core lesson there was: break the review down, verify each layer, don’t trust the whole. Stacked PRs are that idea turned into a git workflow.
What You Need Before Starting
Requirements are light:
- Git — version 2.20 or later. Any recent install works.
- GitHub CLI (
gh) — version 2.90.0 or later per the official quickstart (the repo README still says 2.0+, but the docs are the safer bar). - A GitHub repository you can push to, with Stacked PRs enabled for it.
Check that your CLI is authenticated first:
gh auth status
Then install the official extension:
gh extension install github/gh-stack
That’s the whole setup. The extension is MIT-licensed and lives under the official github/gh-stack repository, so it’s not some random community plugin — this is GitHub’s own tooling.
Step 1: Initialize Your First Stack
Check out your trunk branch — typically main — and create a stack:
gh stack init
Run without arguments, it prompts you for a branch name and offers to use your current branch as the first layer. You can also pass branches directly for a non-interactive setup:
gh stack init feature-auth feature-api feature-ui
This adopts the branches that already exist, creates any that are missing, and wires them into a stack. The trunk defaults to your repository’s default branch, but you can override it with --base:
gh stack init --base develop feature-auth
One detail I appreciate: gh stack init automatically enables git rerere, so conflict resolutions you make once get remembered across future rebases. That saves a surprising amount of pain in a multi-layer stack.
Step 2: Build Layers as You Work
Once the stack exists, you work on the top layer and add new branches as the scope grows. Suppose you’re building a login feature. Start with the auth layer:
gh stack add auth-layer
# ... write code, make commits ...
# New layer on top
gh stack add api-routes
# ... write code, make commits ...
Each gh stack add creates a new branch at your current HEAD, adds it to the top of the stack, and checks it out. There’s no manual git checkout -b, no remembering what depends on what — the stack tracks it all.
Where does the stack live? In .git/gh-stack, a JSON file inside your git directory that tracks which branches belong to which stack and their ordering. It’s never committed to the repo, so it stays a purely local convenience.
Step 3: Submit the Stack as PRs
When the layers are ready, push everything and open the pull requests in one command:
gh stack push
gh stack submit
gh stack submit creates one pull request per branch and links them together as a Stack on GitHub. Each PR’s base is set to the branch below it, so a reviewer looking at PR #2 sees exactly the api-routes diff — not the auth-layer changes it builds on. The linked stack view on GitHub shows the whole chain with a status bar: which PRs are merged, open, or still unpushed.
You can also view the stack locally to check where you are:
gh stack view
The Abbreviated Workflow: Fewer Keystrokes
For small iterations, the extension supports an abbreviated flow that folds staging, committing, and branch creation into a single command:
# Start a stack
gh stack init auth
# Write code for the first layer, then:
gh stack add -Am "Auth middleware"
# → auth has no commits yet, so the commit lands here
# Write code for the next layer:
gh stack add -Am "API routes"
# → auth already has commits, so a new branch is created
# and the commit lands there
The -A flag stages all changes, -m provides the commit message, and the branch name gets auto-generated from the message in date+slug format (something like 08-02-auth_middleware). If you want control over the name, pass it explicitly:
gh stack add -Am "Add tests" test-layer
Want a shorter alias for the whole thing? The extension can set one up:
gh stack alias
# → now "gs push", "gs view", "gs submit" all work
Handling Review Feedback
Here’s where stacked PRs really shine — the middle of the review cycle. A reviewer asks for changes on the bottom PR, the auth layer. You navigate down to it:
gh stack bottom
# ... make changes, commit ...
# Rebase the layers above onto your fix
gh stack rebase
# Push the updated branches
gh stack push
gh stack rebase fetches the latest changes from origin and cascades the rebase up the stack, so every layer above picks up your fix. No manual git rebase --onto gymnastics, no guessing which branch needs what. If a branch’s PR has already been merged, it automatically switches to --onto mode to replay commits correctly on top of the merge target.
If a rebase hits a conflict, the command pauses and prints the conflicted files with line numbers. Resolve them, stage with git add, and continue:
gh stack rebase --continue
# Or bail out entirely:
gh stack rebase --abort
Merging and Staying in Sync
When the whole chain is approved, merge everything up:
gh stack merge
Interactive by default, it lets you pick what to merge — the whole stack, everything up to a specific PR, or just the current branch. The non-interactive form works too:
gh stack merge --yes --squash
After merges land, keep the rest of the stack healthy with one command:
gh stack sync
It fetches, rebases, pushes, and syncs PR state in a single pass, then prompts you to prune merged branches. GitHub’s merge queue also supports stacked PRs now, so you can land an entire chain in one click without breaking CI.
Restructuring Without Pain
Sometimes the review reveals the layers themselves are wrong — this branch should be under that one, or two branches should fold together. The extension has a terminal UI for that:
gh stack modify
It opens an interactive list where you can reorder branches with Shift+arrows, fold one branch’s commits into another, drop a layer, insert an empty one, or rename branches. Everything is staged during preview and applied at once when you save — then gh stack submit pushes the restructured stack back up. It’s a genuinely useful tool for the “wait, this should have been one layer” moment.
AI Agents and the gh-stack Skill
The timing of this release makes sense: GitHub wants coding agents to produce well-structured stacks, not twenty-file monster PRs. The extension ships with a skill your agent can install:
gh skill install github/gh-stack
That teaches a compatible coding agent how to plan layers, create branches, move through the stack, and rebase after mid-stack changes. If you’ve been experimenting with tools like the local-first agent I covered in my Collie tutorial, this is the same philosophy applied to GitHub workflows: let the tooling enforce structure instead of trusting the agent to do it.
And honestly, given how often I’ve seen AI assistants invent things confidently — I wrote about AI assistants hallucinating package names a week ago — anything that makes generated code easier to verify in small pieces is a win for review quality.
When Stacked PRs Make Sense (and When They Don’t)
Stacked PRs aren’t for every change. Here’s my honest take after a week of using them:
Use them when:
- The change is a genuine multi-step feature — auth, then API, then UI.
- You’re working on a branch for more than a day or two.
- Your team is comfortable rebasing and understands the stack model.
Skip them when:
- The change is one small fix — a single PR is simpler.
- Your team uses long-lived feature branches with merge commits and is allergic to rebasing.
- You can’t get the repo enabled for Stacked PRs yet (preview features roll out gradually).
The mental model that helps: think of a stack like a chess opening. You’re not making one big move; you’re building a sequence of small, sound moves where each one sets up the next. A novice tries to win in one dramatic combination. A patient player develops piece by piece, and the win becomes almost inevitable.
Bottom Line
GitHub Stacked PRs with gh stack fixes a real workflow problem: big changes become reviewable again. The extension handles the tedious bookkeeping — branches, bases, rebases — so you can focus on making each layer actually good. Install it, build a three-layer stack on your next feature, and see whether your reviews get sharper. Mine did.