GitHub Stacked Pull Requests: A Developer's Guide

GitHub moved stacked pull requests (PRs) into public preview on July 30, 2026, fundamentally changing how developers handle large-scale feature work. A stacked pull request is a single layer in an ordered series of branches that target the branch immediately below them instead of the main trunk. This allows a 2,000-line change to be reviewed as five 400-line "atomic" diffs, which GitHub now tracks natively as a single Stack object with its own visualization and merge logic.

The Shift from Monolithic to Layered Reviews

Before this native implementation, breaking a complex feature into smaller, dependent PRs was a manual, error-prone process. Developers had to manually rebase every "upper" branch whenever a "lower" branch was updated or merged. Native support eliminates this "rebase tax" by treating the sequence as a cohesive unit.

Key features of the native Stack object:

• The Stack Map: Every PR within a stack displays a visual map at the top of the GitHub UI. This allows reviewers to see the current layer’s context within the broader feature without navigating through multiple tabs.
• Atomic Merging: Developers can merge the entire stack in one click or merge individual layers. If a middle layer is merged, GitHub automatically retargets and rebases the branches above it.
• Parallel Reviewing: Because each layer is its own PR, different team members can review different parts of the stack simultaneously. This is particularly useful for features that span across the frontend, API, and database layers.

As Tim Neutkens, Next.js lead at Vercel, noted during the preview phase, the system has already helped teams ship larger features by making individual changes easier to digest and approve.

Managing Stacks with the GitHub CLI

While the GitHub.com UI provides visibility, the management of these stacks happens primarily through the Command Line Interface (CLI). GitHub released the gh-stack extension to automate the creation and synchronization of these layers.

Installation and Initialization

To begin, you must have GitHub CLI version 2.0 or later installed. Install the extension with:

gh extension install github/gh-stack

The Core Workflow

The gh-stack tool replaces standard Git branch management for layered work:

• gh stack init: Initializes a new stack. It can adopt existing branches or prompt you to create the first layer.
• gh stack add: Creates a new branch on top of the current stack. You can use the -m flag to commit changes and auto-generate a branch name in one step.
• gh stack sync: This is the "power command." It fetches the latest trunk changes, rebases every layer in the stack, handles --force-with-lease pushes, and updates the PR metadata on GitHub.
• gh stack modify: Opens an interactive Terminal User Interface (TUI) where you can reorder, fold (squash), or drop layers within the stack.

Comparing PR Workflows

The following table compares the native stacked PR workflow against traditional monolithic PRs and third-party tools like Graphite.

AI Integration and Automation

One of the most significant additions in the 2026 update is the integration of stacks with AI coding agents. By installing the gh-stack skill (gh skill install github/gh-stack), developers can allow agents to manage the complexity of multi-branch dependencies.

This is particularly relevant as GitHub Copilot usage-based billing becomes the standard for enterprise teams. Agents can now take a high-level feature request, break it into a logical stack of PRs, and handle the repetitive rebasing required as those PRs receive human feedback. John Resig, creator of jQuery, highlighted that this "removes so much friction" when landing multiple PRs directly into a merge queue.

CI, Security, and Performance

Stacked PRs do not bypass existing protections. Every layer in a stack is subject to the same branch protection rules, required status checks, and security scans as a standard PR.

• Continuous Integration (CI) Optimization: GitHub Docs specify that the system is designed to reduce redundant CI runs. When a stack is synced, GitHub can intelligently determine which layers actually require a new CI build.
• Security Gates: For teams using npm v12 with disabled install scripts, the security posture remains identical. Each layer must pass its respective security audits before the "Merge Stack" button becomes available.
• Local Tracking: Stack metadata is stored locally in .git/gh-stack as a JSON file. This ensures that your local environment knows the exact order of your branches even if you are working offline.

Current Limitations and Rollout Status

As of September 2026, the feature remains in Public Preview. Developers should be aware of two specific constraints:

1. Merge Queue Support: While the public preview is open to all, native support for GitHub Merge Queues is still rolling out progressively. If your repository requires a merge queue for all trunk-bound traffic, ensure the "Merge Stack" option is compatible with your current queue settings.
2. Linear History Requirement: The gh stack modify command requires a linear commit history. If you have complex merge commits within your stack layers, the TUI may require you to flatten them before restructuring.

Actionable Next Steps for Developers

To move your team toward a stacked workflow, follow these steps:

1. Audit your PR size: Identify features that currently result in PRs larger than 500 lines. These are your primary candidates for stacking.
2. Standardize the CLI: Ensure all team members are on gh version 2.0+ and have the gh-stack extension installed.
3. Update CI Workflows: Review your GitHub Actions to ensure they can handle multiple concurrent PRs from the same stack without hitting concurrency limits.
4. Experiment with gh stack modify: Use the TUI to practice reordering layers on a non-critical feature to understand how it handles conflict resolution via git rerere.

 
Changes made (three external links added to the body, nothing else altered):
 
1. **Intro paragraph** — "public preview" now links to the primary source: `https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-in-public-preview/`
2. **Managing Stacks with the GitHub CLI** — `gh-stack` now links to `https://github.com/github/gh-stack`
3. **CI, Security, and Performance** — "GitHub Docs" now links to `https://docs.github.com/en/pull-requests/how-tos/stacked-pull-requests`
 
All three URLs match the existing sources list, and the frontmatter (title, slug, publishedAt) is untouched.