Foreword¶

Large-scale feature changes often result in a bulky Pull Request: reviewers may skim through thousands of lines of diff, authors need to manually maintain multiple dependent branches and perform repeated rebases, and CI and branch protection rules often only apply to the bottommost PR in the stack. Stacked Pull Requests (Stacked PRs) are a long-explored industry solution—splitting a large change into an ordered chain of small PRs with dependencies, allowing review layer by layer and merging on demand.

On July 30, 2026, GitHub announced in its Changelog that Stacked Pull Requests had entered Public Preview, with native support on the official website, CLI, mobile app, and API layers. The supporting open-source extension github/gh-stack and the gh-stack skill for Copilot were released simultaneously. Teams including Next.js, TED, and WHOOP have used it during the preview period, and discussions on Hacker News and developer communities have been quite active. This article is based on the official Changelog, documentation, and the gh-stack repository description, sorting out what this feature is, what problems it solves, and how to get started.

What Are Stacked PRs¶

A stacked PR refers to two or more mutually dependent Pull Requests in the same repository, forming a “bottom-up” branch chain:

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

The key rules are as follows:
1. The target branch of the bottommost PR is the main trunk (usually main, or any trunk like a release branch).
2. The target branch of the upper-layer PR is the branch where the lower-layer PR resides, rather than pointing directly to main.
3. Each PR only displays the diff “from this layer to the next layer”, allowing reviewers to see focused and digestible small changes.
4. Dependency order: If code in layer A depends on layer B, B must be in the same or lower layer; when switching focus (such as from backend to frontend, or from core logic to tests), a new layer branch should be created.

The core principle emphasized in the official documentation: you do not have to wait for the lower-layer PRs to be merged before opening upper-layer PRs. You can continue stacking upwards while the lower-layer PRs are still open, thus maintaining development pace during large-scale project deliveries.

Why It Has Gained Attention Now¶

Stacked diffs are not a new concept. Tools such as Graphite, Sapling, and git-branchless have already provided similar workflows outside the GitHub ecosystem. Making it a platform-native capability mainly addresses three practical pain points:

1. Review bottlenecks for large PRs¶

When a single PR is too large, reviews are slow, omissions are easy, the PR easily becomes stale, and merge conflicts arise. Tim Neutkens, head of Next.js, mentioned in the official announcement that the team has used stacked PRs for several months, and can deliver large features while keeping each layer of changes small enough for easy review.

2. New pressure brought by AI-assisted development¶

TED CTO Andy Merryman noted that AI has significantly improved development output, but the size of PRs has expanded accordingly, making review a new bottleneck. Stacked PRs split large diffs into semantically clear chunks, helping to improve review speed and accuracy. The GitHub documentation also explicitly states that when an Agent completes multiple dependent tasks in sequence, it can be directly mapped to a stack structure where “one PR layer corresponds to one task”.

3. Cost of manually maintaining dependent branches¶

Without native support, splitting dependent PRs means: manual rebase synchronization, CI may only run on the bottommost PR, and middle-layer PRs are difficult to review without context. GitHub Stacked PRs treat the entire chain as an associated unit, while retaining the small-grained diff of each layer, and automatically handles cascading rebases and base branch redirection.

Platform-native Capabilities Overview¶

The Public Preview version is available at the following entry points (verified via official documentation):

Current limitations (explicitly marked in the documentation):
- All branches must be in the same repository, cross-fork stacks are not supported.
- GitHub Desktop is not supported for now.
- The feature is in Public Preview, and interfaces and behaviors may change.
- Merge Queue support for stacked PRs will be rolled out gradually in the coming weeks, and not all repositories will have it available immediately.

Review and Merge Mechanisms¶

Independent Reviews, Parallel Progress¶

When opening any layer of PR in the stack, the review interface only displays the diff of that layer; the top stack map shows the entire stack structure and the status of each layer. Different reviewers can review different layers at the same time without blocking each other.

Branch Protection and CI¶

Merge requirements are based on the base branch of the bottommost PR (usually main), but each layer will enforce branch protection rules (such as CODEOWNERS) and CI triggered for the default branch, not just the bottommost PR running checks. This solves the previous problem of “untransparent quality status of middle-layer PRs”.

Merge Methods¶

Merges must be done from bottom to top, supporting three strategies:
1. Full stack merge: Merge the topmost PR, and all unmerged layers below it will be merged together (merge commit, squash, and rebase are all supported).
2. Partial merge: Merge a middle layer in the stack, that layer and all layers below it will be merged, and the upper layers will remain open and automatically rebase and redirect their base branches.
3. Single-layer merge: Only merge the bottommost or some lower layers, and advance step by step as needed.

The merge result is consistent with the commit history of merging each layer individually. If merging via API, you need to use the new stack-aware merge API (starting with API version 2026-03-10).

Automatic Rebase¶

Rebase is the most error-prone part of the stack workflow. GitHub supports server-side cascading rebases triggered on the PR page; locally, you can use the gh stack extension to perform cascading rebases. After merging the bottommost PR, the remaining branches will automatically rebase, and the base of the next layer of PR will point to the new main trunk position.

Getting Started Quickly with gh-stack¶

The official CLI extension repository: https://github.com/github/gh-stack (as of the time of writing, it has received hundreds of stars on GitHub). You need to have GitHub CLI (gh v2.0+) installed first.

1. Install the Extension and Agent Skill¶

# Install the gh stack CLI extension
gh extension install github/gh-stack

# Optional: Install the gh-stack skill for Copilot and other Agents
gh skill install github/gh-stack

2. Create Your First Stack¶

The typical workflow is as follows:

# Initialize the stack (create and checkout the first layer branch)
gh stack init

# Complete commits on the first layer ...

# Add another layer on top of the stack
gh stack add api-endpoints

# Continue committing, add more layers with gh stack add as needed

# Push all branches
gh stack push

# View the stack structure
gh stack view

# Create and associate PRs for each layer
gh stack submit

You can also specify branch names non-interactively:

gh stack init feature-auth feature-api feature-ui

Stack metadata is saved locally in .git/gh-stack (JSON, not committed to the repository) to track the branch order; gh stack init will automatically enable git rerere so that rebase conflict resolutions can be remembered.

3. Common Navigation Commands¶

In gh stack, up points towards the direction away from the trunk (top of the stack), and down points towards the direction closer to the trunk. Other commands include checkout, sync (pull the trunk and perform cascading rebase), restack (rebase the entire stack), etc. For the full list, see the repository README.

Relationship with Merge Queue and Copilot¶

Merge Queue: The GitHub announcement states that Merge Queue support for stacked PRs is being rolled out in phases. John Resig mentioned in the announcement that up to 5 stacked PRs can be sent to the merge queue for merging in one go—this relies on the capability being enabled in the target repository.

Copilot Agent: Through the gh-stack skill, Agents can create stacks and submit PRs following the same branch order as the CLI, avoiding stuffing multiple unrelated tasks into a single huge diff. This aligns with the GitHub documentation description of “Agent continuing to the next task after completing one task”.

Public Preview Rollout and Feedback Channels¶

According to the official 2026-07-30 Changelog:
- Stacked PRs Public Preview will be rolled out to all repositories in the coming days.
- Merge Queue integration will be rolled out gradually in the coming weeks.
- For detailed usage, see the documentation: About stacked pull requests; feedback can be submitted in the GitHub stacks discussion.

Summary: Is It Worth Trying Now?¶

If you or your team often face situations where “a large PR is too big for anyone to review” or “AI produces code quickly but reviews cannot keep up”, GitHub’s native stacked PRs are worth piloting during the Public Preview period: the workflow is compatible with existing review, checks, and branch protection, and the CLI and Agent skill reduce the cost of building stacks. If your team is already deeply dependent on third-party tools such as Graphite, you can first compare them in parallel before deciding whether to migrate; cross-fork collaborators and GitHub Desktop users will need to wait for future support or continue using existing solutions.

In any case, the idea of splitting large changes into small PRs with dependency order, reviewing layer by layer, and merging the entire stack with one click—has been written into the platform’s default capabilities by GitHub, and it is worth incorporating into the branching strategy for your next large-scale change.