Preface¶

Large feature changes often result in a massive Pull Request: reviewers have to sift through thousands of lines of diffs, CI pipelines take a long time to run, feedback cycles are stretched, and merge conflicts are more likely to pile up. Many teams manually split changes into multiple dependent branches and PRs, but the maintenance costs of rebasing, aligning with the base branch, and verifying CI status across each layer are not low.

On July 30, 2026, GitHub announced that Stacked Pull Requests (Stacked PRs) had entered Public Preview. This feature breaks large changes into an ordered, independently reviewable chain of PRs, and unifies management across the Web, CLI, mobile apps, and Copilot Agents. Reviewers can parallelize reviews across different layers, and the entire stack can be merged with one click. This article outlines the core mechanisms and getting-started guide for this feature based on GitHub’s official Changelog and documentation.

Note: Stacked PRs are currently in Public Preview, and features and APIs may change; Merge Queue support for stacked PRs will roll out gradually over the coming weeks.

What Are Stacked PRs¶

Stacked PRs refer to a dependency chain of two or more Pull Requests in the same repository:
- The bottommost PR uses the main branch (usually main) as its base;
- Each subsequent PR’s base is the branch of the PR layer above it.

The schematic structure is as follows:

   ┌── feat/frontend      → PR #3 (base: feat/api-endpoints)  ← Top layer
  ┌── feat/api-endpoints  → PR #2 (base: feat/auth-layer)
 ┌── feat/auth-layer      → PR #1 (base: main)               ← Bottom layer
main (default main branch)

Each PR layer only displays the diff of the current branch relative to the layer above it, rather than the cumulative difference of the entire change set. Shared types, database schemas, and other foundational changes are placed in lower layers; API and UI logic that depends on them goes in higher layers. The official documentation emphasizes one core principle: If code in layer A depends on layer B, B must be in the same or lower layer.

Why the Community Has High Interest in This Feature¶

Stacked PRs are not a new concept — tools like Graphite and ghstack have already implemented similar workflows in the GitHub ecosystem. With native support from GitHub this time, several pain points are directly resolved:
1. Branch Maintenance: Rebasing across the dependency chain is automatically handled cascadingly by GitHub’s servers or the gh stack CLI. After merging a bottom-layer PR, upper-layer branches will automatically rebase and retarget.
2. Rules and CI: Previously, chained PRs often only had the bottommost PR fully trigger branch protection and CI; now every layer in the stack will enforce the same protection rules and PR-triggered Actions checks as the base branch (usually main).
3. Review Context: The PR page on the Web will display a stack icon and stack map at the top, allowing reviewers to clearly see the current layer’s position in the overall change.

In the context of widespread AI-assisted coding, this feature is also explicitly positioned by the official team for “high-productivity development” scenarios: after an Agent completes one task, it immediately moves to the upper layer for the next task, with each layer corresponding to one PR, avoiding mixing unrelated changes into the same branch.

Tim Neutkens, Head of Next.js, and John Resig, Creator of jQuery, all mentioned in the GitHub announcement that stacked PRs help teams advance large features while maintaining small-batch reviews. John Resig specifically noted that combining the gh CLI with Agent skills allows sending multiple stacked PRs into the Merge Queue in one go.

Where to Use Stacked PRs¶

According to the official documentation, stacked PRs currently support the following entry points:
| Entry Point | Description |
|------|------|
| GitHub Website | Stack map, layer navigation, one-click merge of the entire stack |
| GitHub CLI | gh stack extension, responsible for local creation, rebasing, and committing |
| GitHub Mobile | View and operate stacks on mobile |
| Webhooks / REST / GraphQL | Automated integration, with stack object included in payloads |
| Copilot and other Agents | Drive the CLI via the gh-stack skill |

Not yet supported: GitHub Desktop; cross-fork stacks (all branches must be in the same repository).

Quick Start: gh stack CLI¶

Environment Requirements¶

• GitHub CLI (gh) 2.90.0 or higher, Git 2.20 or higher
• Completed authentication with gh auth login
• Push permission for the target repository

Install the Extension¶

gh extension install github/gh-stack

If you need to use it with Copilot and other AI Agents, you can additionally install the skill:

gh skill install github/gh-stack

Create Your First Stack¶

1. Initialize a stack in the repository directory. The CLI will create tracking records and generate the first branch:

   gh stack init

2. Write code and make commits normally at the current layer:

   git add .
   git commit -m "Add auth middleware"

3. When starting a new logical unit, add a new branch at the top of the stack:

   gh stack add feat/api-routes
   # Continue development and commit ...

4. Push all branches:

   gh stack push

5. Create PRs and link them as a stack on GitHub:

   gh stack submit

The first PR will have main as its base, and each subsequent PR will use the branch of the lower layer as its base. Reviewers will only see the diff for the layer they are responsible for.
6. View the full stack at any time:

   gh stack view

Quick Reference of Common Commands¶

Web-Based Review and Merge¶

Opening any PR in the stack will display a layer number and stack map at the top of the page, allowing one-click navigation to other layers. Different reviewers can parallelize reviews across different layers without blocking each other.

Key merge rules:
- Merges must be done from bottom to top;
- When merging the top-layer PR, all unmerged layers below it will be merged together;
- If only a middle layer is merged, that layer and all layers below it will be merged, while upper-layer PRs will remain open and automatically retarget;
- Supports three merge methods: merge commit, squash, and rebase, and is compatible with Merge Queue (support is rolling out gradually).

Relationship with Merge Queue and Copilot¶

The Merge Queue is used to queue CI runs before merging and avoid main branch conflicts; the official team stated that Merge Queue support for stacks is being rolled out in phases. John Resig’s use case in the announcement was “sending 5 stacked PRs into the merge queue at once”, indicating the target scenario is: after multiple layers of changes have passed reviews and checks, they enter the main branch in order as a whole.

On the Copilot side, the gh-stack skill allows Agents to understand stack semantics — operations like creating branch chains, pushing, submitting, and rebasing can all be called by Agents, making it ideal for scenarios where AI produces multiple consecutive changes. GitHub’s documentation also provides a tutorial titled Stack AI-generated code in pull requests that guides how to organize Agent outputs into stacks.

Important Notes for Usage¶

1. Public Preview Stage: APIs are subject to updates. If merging stacks via the REST API, you need to use the new version of the merge API that supports stacks (the documentation specifies API version 2026-03-10).
2. Repository Scope: Stacks between forked repositories are not supported.
3. Split Granularity: Each layer should be an independently reviewable logical unit; it is appropriate to create a new layer when switching between frontend and backend, core logic and tests, and other “different areas of concern”.
4. Rollout Schedule: The feature will be rolled out to all repositories in the coming days; Merge Queue integration will have to wait for subsequent updates.

Summary¶

GitHub Stacked PRs bring the long-standing problem of “large PRs being hard to review and chained branches being hard to maintain” into the native workflow: parallel reviews of small layers, rules and CI taking effect layer by layer, one-click merge of the entire stack, and rebase managed by the platform. For teams accustomed to third-party tools like Graphite, this is an option to “use stacks without changing platforms”; for teams using Copilot to accelerate output, it provides a way to structure Agent outputs into a standardized workflow.

If your team is being slowed down by giant PRs, you can start with gh extension install github/gh-stack, test stack splitting with a small feature, and then experience the stack map and full-stack merge on the Web. During the Public Preview, feel free to share your experience in the GitHub stacks discussion.