Preface¶

Stacked Pull Requests (Stacked PRs) are not a new concept — at companies like Meta and Google, breaking large changes into a chain of dependent small PRs using tools such as Graphite and Sapling has long been a mature practice. For a long time, however, GitHub did not offer first-class support for this workflow: you either had to endure a thousand-line giant PR, or manually maintain multiple branches, repeatedly rebase, and get stuck resolving merge conflicts.

On July 30, 2026, GitHub announced in its Changelog that Stacked Pull Requests had entered Public Preview; on August 4, the official engineering blog published a detailed article explaining how to split the “giant AI PR” output by Agents into a reviewable stacked chain. Combined with the gh stack CLI extension and the Stack Map on the PR page, this capability finally evolved from a “community plugin” into a native GitHub workflow.

For teams that extensively use coding Agents such as Copilot, Cursor, and Claude Code, this news carries significant weight: the more capable the Agent, the larger the diff of a single PR often becomes; code review has become a new bottleneck. Stacked PRs are GitHub’s official solution — not to make you write less code, but to allow code to be delivered in a way that is “small-step, reviewable in parallel, and mergable with one click”.

This article organizes the problems Stacked PRs solve, how to get started with them, and details worth noting when collaborating with AI Agents, based on information verified from GitHub’s official blog and documentation.

Why Giant PRs Have Become a Pain Point in the AI Era¶

GitHub’s engineering blog uses a very typical scenario as an example: adding a “product search” feature to a shopping assistant. You feed a prompt to an Agent, and when you come back a few minutes later, the PR may already include:
- New data models and seed data
- API routes and validation logic
- Client-side wiring, UI, and handling of empty/error states

One PR with over 1700 lines of diff, and the description generated by the AI is “long and superficial”. The real reaction of reviewers is often: “I’ll take a look another day.”

The blog cites a Gartner forecast: by 2028, coding Agents are expected to deliver approximately 50% productivity improvement across every SDLC stage. As productivity rises, PR size swells along with it — yet review speed has not kept pace. Andy Merryman, CTO of TED, mentioned a similar dilemma in the Changelog: “AI has supercharged developer efficiency, but PRs have grown too large for reviewers to handle.”

The traditional binary choice is awkward:
1. One giant PR: Difficult to review, poor feedback quality, slow to merge, often force-merged without adequate review.
2. Split into multiple small PRs manually: Logically clearer, but requires maintaining branch dependencies manually, performing rebases, and resolving conflicts, with high maintenance costs.

Stacked PRs attempt to strike a balance between the two: split the work structurally into smaller parts, and let the tool automatically manage dependencies.

Core Idea of Stacked PRs: Layer by Dependencies¶

The principle boils down to four words: decomposition.

Instead of solving an entire Issue with one PR, split the feature into multiple layers with logical dependencies, where each layer focuses on a single responsibility and is small enough for reviewers to “hold in their heads”. The base of an upper-layer PR is the next (more underlying) branch, rather than pointing directly to main.

In the official example, the “product search” feature is split into four layers:

The benefit is that reviews can be assigned by expertise: the data layer to the data owner, the UI to the frontend owner, without blocking each other. Tim Neutkens, maintainer of Next.js, noted in the Changelog that after the Vercel team adopted Stacked PRs, “large features are split into small changes, making reviews much easier”.

Getting Started: gh stack CLI and Agent Skill¶

Install the CLI Extension¶

The management entry for Stacked PRs is the GitHub CLI extension github/gh-stack. The official documentation requires GitHub CLI 2.90.0+, Git 2.20+, and completed gh auth login authentication.

gh extension install github/gh-stack

Teach Agents the Stacked Workflow¶

If you use Copilot or other Agents that support Skills, you also need to install the gh-stack skill to let the Agent know how to create and manage stacks:

gh skill install github/gh-stack

Or:

npx skills add github/gh-stack

The Changelog explicitly states that Stacked PRs can be used on github.com, GitHub CLI, GitHub Mobile App, and coding Agents such as GitHub Copilot.

Create Your First Stack¶

The typical workflow is as follows (commands are based on the official Quickstart):

1. Initialize the stack and create the first layer branch:

gh stack init

You will be prompted to name the first branch; the repository’s default branch (usually main) is used as the trunk (stack base) by default. This is critical: CI and merge rules throughout the stack’s lifecycle are evaluated relative to the stack base.

2. Append the next layer on top of the current layer:

gh stack add -Am "commit message describing changes in this layer"

If the current branch has no commits, the changes will be applied to the current layer; if there are already commits, a new branch will be automatically created as the upper layer.

3. Push to the remote repository:

gh stack push

4. Create PRs and link them into a stack on GitHub:

gh stack submit

The base of each PR will be set automatically: the first layer points to main, and subsequent layers point to the previous layer’s branch. When a reviewer opens a PR, they will only see the diff for that layer and will not be overwhelmed by changes from upper or lower layers.

5. View the full stack at any time:

gh stack view

Other common commands include gh stack rebase (cascading rebase), gh stack sync (fetch + rebase + push + sync PR status), and gh stack merge (merge one or more layers in the stack). See the official CLI reference documentation for the full command list.

PR Page: Stack Map and Review Strategy¶

Once a stack is submitted to GitHub, a Stack Map will appear at the top of each PR — a clickable navigation map that lets you quickly jump between layers of the stack.

The official recommended review order is worth remembering:
- Read top-down: Start with the top layer of the stack to understand the ultimate goal — “Oh, this is to display product cards in the chat interface.”
- Review bottom-up: Start reviewing from the bottom of the stack (the layer closest to main) and work your way up, with each layer’s implementation built on the understanding that the previous layer has passed review.

In this way, a 1700-line monolith diff is split into four separate review units, and different reviewers can even review different layers in parallel without blocking each other.

Rebasing After Changing the Underlying Layer: Avoid the Signed Commit Pitfall¶

Stacks are not “set it and forget it”. The engineering blog specifically covers a common scenario: a reviewer leaves feedback on the bottom layer (L1) of the stack, and after the Agent or developer fixes the issue and pushes, the upper branches will diverge from the underlying layer. GitHub will clearly prompt: “Some branches in this stack have diverged and must be rebased”, and display Unable to merge as a stack.

At this point, a one-click Rebase stack button will appear on the PR page. But the official specifically warns: Clicking this button on the web will perform the rebase on GitHub’s servers, and the committer of the resulting commit will be the person who clicked the button, and the commit will not be signed. If your branch protection rules require signed commits, this one-click operation may silently cause merge failures.

A more reliable approach is to run the command locally:

gh stack rebase
gh stack push

If you need to synchronize the entire stack’s status in one go, you can use:

gh stack sync

This command will fetch, perform a cascading rebase on the stack, push the changes, and synchronize the PR status on GitHub — underlying changes can “ripple upward” without manually modifying L2, L3, or L4.

Merging: Land the Entire Stack with One Click¶

A major selling point of the Public Preview is the merge experience. You can:
- Merge the top of the stack: Land all unmerged layers from the stack base to the top in one go (the Changelog calls this “one click merge everything”).
- Merge only some layers: After merging lower layers, the upper PRs will remain open and automatically rebase and retarget.

Existing branch protection, required checks, and review rules remain in effect — Stacked PRs are built into GitHub, not a bypass tool. John Resig, creator of jQuery, mentioned in the Changelog that using the gh CLI + agent skill with stacks allowed “5 stacked PRs to go directly into the merge queue and be merged all at once”.

It is important to note: Support for merge queues with Stacked PRs is still rolling out progressively (per the Changelog: rolling out progressively over the coming weeks). If your team heavily relies on merge queues, it is best to verify this in your own repository before going live.

Practical Advice for Collaborating with AI Agents¶

Combined with examples from the official blog, here are several actionable conclusions:

1. Constrain “one responsibility per layer” in your prompt. Do not let the Agent modify the data layer, API, and UI in one branch; assign different layers to Agents with different expertise in the order of L1 → L4 (data modeling, backend, frontend), and run CI before committing each layer.

2. Ask three reviewer questions before merging each layer (a reviewer’s note template from the blog):
- L1: Are the types correct? Is the data validated? Are the query helpers secure?
- L2: Is the input validated? Is the response contract stable? Should errors/empty states be handled here or downstream?
- L3: Can every answer be traced back to a real API response? What happens if the API fails or returns no results?
- L4: Do references link back to real products? Are the loading/empty/error states fully implemented?

3. Even the same author (or the same Frontend Agent) can split into multiple layers. The blog intentionally separates L3 (wiring) and L4 (UI) — the UI owner does not need to re-review the data flow, making review boundaries clearer.

4. Prioritize local rebases, and avoid using the one-click web rebase. This is especially true for teams with signed commit requirements or strict audit mandates.

5. Use the stack for parallel reviews, but keep the stack base stable. Once the stack base changes, the CI evaluation baseline for the entire chain will shift; try to avoid disruptive changes being pushed to main during large feature development.

Final Notes¶

Stacked PRs are not magic that “reduces the load” of code reviews — reviewers still need to read diffs, leave feedback, and uphold quality standards. What they change is the granularity of reviews and the way of collaboration: turning “one giant PR no one wants to open” into “a chain of small PRs that can be assigned, reviewed in parallel, and merged layer by layer”, and taking over the tedious manual work of rebasing, linking, and merging through native GitHub tools.

For AI coding Agents, this capability is particularly well-suited: Agents naturally tend to “write the entire feature at once”; gh stack + the gh-stack skill provide a structured delivery template for both Agents (and humans). The Public Preview is gradually rolling out to all repositories, so try it on your next large diff generated by an Agent — first run gh stack init, then add layers one by one by dependencies, and finally use the Stack Map to invite colleagues to review in parallel.

References:
- Turn one giant AI-generated pull request to a reviewable stack（GitHub Engineering Blog, 2026-08-04）
- Stacked pull requests are now in public preview（GitHub Changelog, 2026-07-30）
- Stacked pull requests quickstart（GitHub Docs）