GitHub Stacked PRs: Split Changes with Base Branches and gh stack (2026)

GitHub stacked pull requests let you split a large change into an ordered chain of layer PRs and review each layer on its own. The feature entered public preview on 2026-07-30.

📑Table of Contents

1. What stacked PRs are: layers, bases, and the stack map
2. Why this matters now: AI-agent review bottlenecks
3. How to use it: Web UI, gh stack CLI, and the skill
4. Split patterns for parallel AI-agent work
5. Comparison table and adoption checklist
6. FAQ
7. Closing: decide today, verify this week

What the product packages together:

• Merge one, some, or all layers from the bottom
• Automatic rebase and retarget for remaining upper layers

As AI coding agents make oversized diffs more common, this article turns official docs and independent hands-on reports into a practical decision frame: when to stack, how to split, and what to verify before team rollout.

Learning outcomes

---

What stacked PRs are: layers, bases, and the stack map

Definition and base chain

A stacked PR is an ordered chain of pull requests in the same repository.

• The bottom layer targets trunk (usually main)
• Each upper layer targets the branch below it
• Reviewers see a focused layer diff instead of one monolithic patch

Dependencies, UI, and protections

Dependencies should live in the same layer or a lower branch. Upper layers may build on still-unmerged lower work.

Avoid splits that make the stack cosmetic:

• Cyclic dependencies
• Dumping everything into a UI layer

UI and protection points:

• Stack numbering and a stack map in the merge box
• Branch protection and required checks apply across mid-stack PRs against the bottom base
• Cross-fork stacks are not supported
• Because this is public preview, treat CLI names and UI copy as time-stamped

Primary sources

• GitHub Docs: About stacked pull requests
• GitHub Changelog (2026-07-30)

---

Why this matters now: AI-agent review bottlenecks

Why giant PRs keep showing up

As agents ship more code faster, 1000+ line PRs become easier to open and harder to review.

• Generation speed does not remove human review and CI judgment
• Manual PR splitting still leaves expensive base retargets
• Rebase chains and partial-merge cleanup remain heavy

What native stacking packages

Native stacking packages three operational promises:

1. Focused per-layer diffs
2. Cascade rebase after a lower merge
3. One-click merge of one/some/all layers while keeping reviews, checks, and merge requirements

Merge-queue support was described as rolling out gradually at changelog time.

AI-context framing

GitHub Engineering shows a concrete decomposition pattern for a product-search change:

• catalog-data
• search-api
• chat-grounding
• grounded-ui

Specialized agents and reviewers can sit on each layer. Independent coverage also frames stacking as a way to turn AI-generated bulk into dependency-ordered review units without dropping branch protections.

Sources:

• GitHub Engineering (2026-08-04)
• DevOps.com

---

How to use it: Web UI, gh stack CLI, and the skill

Choose the entry point

Choose the entry point by where your team works.

• Web: start from Preview stack / Create stack
• Local: install the extension

gh extension install github/gh-stack
# for agent workflows where supported
gh skill install github/gh-stack

GitHub’s Copilot tutorial lists prerequisites such as gh 2.90.0+, the extension, the skill, and Copilot CLI. Verify versions in your environment before standardizing.

Core CLI flow

1. gh stack init — start the bottom branch/stack (some reports also cover importing an existing branch)
2. Implement, then gh stack add — append an upper layer
3. gh stack view — inspect local stack state
4. gh stack submit — push, open PRs, update bases, and create the GitHub stack (some demos use --auto for multi-PR creation)
5. gh stack sync — fetch/rebase/push to keep the stack coherent (--prune can drop merged local branches)
6. gh stack merge — merge a selected PR and the layers below it when that path fits your process

Edit, review, and merge habits

Edit commands

Edit commands that appear in independent hands-on writeups:

• modify
• rebase
• link
• fold
• drop

Use them when reordering or inserting layers.

Review and merge habits

Operational habits:

• Read top-down
• Review bottom-up
• Put fixes on the owning layer
• Rebase the upstack
• Always merge from the bottom so remaining upper layers retarget automatically

Sources for this section

• Classmethod DevelopersIO
• gihyo.jp
• Ubie on Zenn
• GitHub Docs: Stack AI-generated code in pull requests

---

Split patterns for parallel AI-agent work

Design the graph first

Do not treat “one agent run = one giant PR” as the default.

Design the dependency graph first, then generate and review layer by layer.

Decision criteria

• Does build/type/contract stay closed in lower layers?
• If you revert only the upper layer, does the lower layer still make sense?
• Does CI against the stack base produce meaningful per-layer failures?
• Can review lenses (data / API / UI / wiring) stay separated by layer?

Reader translation of the official example

A practical reader translation of the official example is:

• schema → API → wiring → UI

Parallel worktrees or issue-scoped agent runs can still land later as a serial dependency stack if the graph is explicit.

Failure modes and agent skill use

Common failure modes:

• Cyclic dependencies
• Cosmetic layer names
• Rushing upper merges before lower review
• Missing protection / CODEOWNERS / required-check policy for mid-stack PRs

Where available, install the gh-stack skill so agents can:

• Inspect stack state
• Follow init / add / submit
• Avoid inventing branch choreography

---

Comparison table and adoption checklist

Diff shape and dependencies

Dimension	One giant PR	Manual split PRs	GitHub stacked PRs (preview)
Diff shape	Everything in one view	Split, but bases are manual	Focused layer diffs + stack map
Dependency expression	Implicit	Branch names and prose	Ordered base chain
Merge	All-or-nothing or risky partial apply	Hand retarget from the bottom	One/some/all + auto rebase/retarget

CI, AI-agent fit, and cost

Dimension	One giant PR	Manual split PRs	GitHub stacked PRs (preview)
CI / protection	One huge check surface	Easy to configure inconsistently	Official mid-stack protection/check model
AI-agent fit	Easy to dump output; hard to review	Heavy cleanup afterward	CLI/skill can operationalize layering
Main cost	Review load	Operator mistakes	Preview learning, split design, tool churn

Sources synthesized from GitHub Docs/Changelog/Engineering plus Classmethod, gihyo.jp, and DevOps.com (as of August 2026).

Reader next actions

1. Take one recent giant PR or agent output and write a four-line dependency layer plan (for example schema → API → wiring → UI).
2. On a non-production sample repo, install github/gh-stack and run init → add → submit once.
3. Inspect branch protection, required checks, and CODEOWNERS behavior on mid-stack PRs via the stack map.
4. Partially merge the bottom layer and observe automatic upper retarget/rebase.
5. If agents are in play, install the gh-stack skill and template a “define layers first” prompt.
6. Add a one-page team rule: review bottom-up, fix on the owning layer, no cyclic dependencies.
7. Assign someone to re-check Changelog/Docs CLI drift while the feature remains in preview.

Fit and unfit cases

Good fit:

• Vertically layered features with clear contracts
• Parallel agent work with low file collision
• Medium-to-large changes that benefit from separated review lenses

Poor fit:

• All-or-nothing cutovers
• Fork-based workflows
• Tiny repos where trunk strategy is still undefined and stacking overhead exceeds review gain

---

FAQ

Q1. How is a stacked PR different from ordinary dependent branches?

Both stack branches. Native GitHub stacking adds these as product behavior:

• Stack map
• Layer-only diffs
• Partial/full merge with automatic rebase/retarget
• Mid-stack protection/check application

Q2. Is gh stack required, or is the Web UI enough?

You can start from Create stack on the Web. Local layering, sync, and agent workflows center on the CLI and skill. Pick the path that matches where work already happens.

Q3. Can we dump one agent run into one stack as-is?

Prefer designing dependency-ordered layers first, then generate and review per layer. That matches the official AI stacking tutorial better than carving a monolith after the fact.

Q4. Can we merge a middle layer first?

Merge from the bottom. Lower merges cascade to upper layers. Do not design as if middle-only merges are the normal path.

Q5. Can a long existing feature branch become a stack later?

Hands-on reports mention init import and modify/reorder flows. History surgery collides easily, so rehearse on a throwaway repo before touching a critical series.

Q6. Is public preview safe for production monorepos?

It is still preview, and some merge-queue behavior was staged. Validate partial merge and required checks on staging, then roll out with explicit team agreement.

Q7. What about third-party stacking tools such as Graphite?

If you already run an external stack workflow, compare native benefits (protection integration, CLI/skill) against migration cost. This article does not endorse a vendor.

---

Closing: decide today, verify this week

Stacked PRs are not only a “make PRs smaller” trick. They make dependency-ordered review units first-class on GitHub.

In an AI-agent workflow, the core is:

• Split design
• Bottom-up review

CLI and skill keep that process from collapsing back into branch thrash.

This week:

1. Run init / add / submit and one partial merge on a sample repository
2. Check fit against your protection rules

Do not standardize a monorepo solely on discovery popularity or a single company blog.

Evidence order:

1. Start from GitHub’s primary docs
2. Corroborate with independent hands-on sources such as Classmethod, gihyo, Ubie, and DevOps.com

Final permission and release policy stay with each team.