GitHub Stacked PRs: What They Are and How to Use Them

GitHub has made stacked pull requests generally available, giving developers a better way to work on large features without turning every change into one enormous pull request.

The idea is straightforward: instead of waiting for one pull request to merge before starting the next, you can build a series of smaller pull requests where each one depends on the changes below it.

This is particularly useful when multiple developers are working on the same feature, when backend and frontend changes depend on each other, or when a large change is difficult to review in one sitting.

Let's look at how stacked PRs work, what problems they solve, and how to start using them.

What are stacked pull requests?

A stacked pull request is a pull request built on top of another pull request's branch rather than directly on main.

Each PR contains a focused part of a larger change. The first establishes the foundation, the next builds on it, and subsequent PRs add more functionality.

Consider a feature that requires a database schema change, new API endpoints, and a frontend interface.

A typical workflow might look like this:

• PR #1: Add the database schema.
• PR #2: Implement the API endpoints using that schema.
• PR #3: Build the frontend using the new API.

Without stacking, you might put all three changes into one PR or wait for each PR to merge before moving on. Stacked PRs let you keep the changes separate while preserving their dependencies.

The branch structure looks like this:

main
 └── feature/database        → PR #1
      └── feature/api        → PR #2
           └── feature/ui   → PR #3

PR #1 targets main. PR #2 targets feature/database, and PR #3 targets feature/api.

Each PR has its own scope and review, while the complete feature remains connected.

Why stacked PRs are useful

1. Developers don't have to wait for every PR to merge

Suppose one developer is building a database layer and another needs that layer to implement an API.

In a conventional workflow, the second developer may have to wait for the database PR to merge before starting work against main. Alternatively, they might create a temporary branch and manually manage the dependency.

With stacked PRs, the API developer can branch from the database developer's branch and start working immediately.

The API PR can be reviewed while the database PR is still open. Once the database changes are merged, GitHub can update the dependent branches as the stack progresses.

This doesn't eliminate every coordination problem, but it reduces unnecessary waiting when one change depends on another.

2. Code reviews become easier to follow

A 1,500-line PR that changes the database, API, frontend, and tests is difficult to review carefully.

Splitting it into smaller PRs gives reviewers a narrower question to answer each time: Is the database change correct? Does the API behave as expected? Does the frontend handle the response properly?

Reviewers can focus on the logic of each layer without losing sight of the larger feature.

3. Parallel work becomes more practical

Stacking is useful when developers are working on related parts of the same feature.

One developer can establish a shared interface or foundational implementation while another builds on it. Both can make progress before the first change reaches main.

There is an important distinction, though: stacked PRs manage dependencies between branches; they don't automatically resolve two developers editing the same lines of code. If both people change the same section, Git conflicts or conflicting design decisions may still need to be resolved.

The benefit is that dependencies are explicit and easier to manage, rather than hidden in a collection of temporary branches.

How to use GitHub stacked PRs

GitHub supports creating stacks through its website or the GitHub CLI. The CLI is a convenient option if you already spend most of your time in the terminal.

Step 1: Install the GitHub CLI extension

Make sure GitHub CLI is installed, you're authenticated, and your repository is available locally.

Install the stacked PR extension:

gh extension install github/gh-stack

You can then navigate to your repository and initialize a stack:

cd your-repository
gh stack init database

This creates the first branch in the stack, using your repository's default branch as the base unless you specify another trunk.

Step 2: Create the first PR

Implement the foundational change. In our example, that means adding the database schema.

Stage and commit the changes:

git add .
git commit -m "Add database schema"

This is the first layer of the stack.

Step 3: Add another branch on top

Now create the API layer:

gh stack add api

The new branch is created on top of the current stack layer. Implement the API, then commit the changes:

git add .
git commit -m "Add API endpoints"

Repeat this process for each additional layer. For example, you could add a frontend branch on top of api and implement the interface there.

Step 4: Submit the stack to GitHub

When the changes are ready to share, push and create the pull requests:

gh stack submit

The CLI creates the PRs with the appropriate base branches and links them as a stack. Each PR can then be reviewed as an individual layer.

To inspect your stack or push updated branches, use:

gh stack view
gh stack push

For the complete command reference and current requirements, see the official GitHub stacked PR quickstart.

Can you create stacked PRs without the CLI?

Yes. If you prefer the GitHub website, you can create the same branch structure manually.

1. Create the first PR against main.
2. Create a second branch based on the first branch.
3. Open a PR for the second branch, selecting the first branch as its base.
4. Use GitHub's Create stack option to link the pull requests.
5. Repeat for any additional layers.

GitHub displays stack information in the PR interface, helping reviewers understand the relationship between the changes.

If you already have open PRs with the correct dependency structure, GitHub may also offer to convert them into a stack.

See the official guide to creating stacked pull requests for the full workflow.

How do you merge a stack?

You don't have to merge every PR separately.

You can merge the entire stack when all its layers are ready. You can also merge a lower or middle PR first, leaving the higher layers open to continue development.

For example, once the database and API changes are ready, you can merge those layers while the frontend PR remains open. GitHub updates the remaining stack as the underlying branches change.

Your repository's branch protection rules, required reviews, and status checks still apply. Stacking changes how dependent PRs are organized; it isn't a shortcut around code review.

When should you use stacked PRs?

Stacked PRs are a good fit when:

• A feature has several dependent layers.
• A large change is difficult to review as one PR.
• Multiple developers need to work against code that hasn't merged yet.
• You're building a feature in a monorepo or working through a large refactor.
• You want to break AI-assisted coding work into smaller, reviewable changes.

They are less useful when changes are genuinely independent and can be developed on separate branches. In that case, ordinary PRs are simpler.

You should also be careful with deep stacks. If a foundational change needs substantial rework, every layer above it may need adjustments. Keep the dependency chain as short and focused as practical.

Final thoughts

Stacked PRs make an existing Git workflow easier to manage. Instead of treating a large feature as one unit or manually coordinating a collection of dependent branches, you can organize the work into smaller pull requests with explicit dependencies.

The biggest benefit isn't simply having more PRs. It's being able to keep development moving while making each change easier to understand, test, and review.

If your team regularly works on features that span several layers, GitHub stacked PRs are worth trying.

At Pie.host, we build infrastructure for developers who want to spend less time managing complexity and more time shipping software. Explore Pie.host to learn more about our developer cloud and infrastructure products.