About stacked pull requests

About stacked pull requests

Stacked pull requests are two or more pull requests in the same repository, where:

• The first, or bottom, pull request targets the stack's trunk — usually your repository's default branch, such as main, though it can be any branch, such as a release branch.
• Each subsequent pull request targets the branch of the pull request below it.

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

Stacked branches form a dependency chain, where each branch builds on the one below it. Foundational changes such as shared types and database schema go in lower branches, and code that depends on them, such as API routes and UI components, go in higher branches.

Each pull request in a stack represents a discrete, reviewable change of one or more commits. You can review and iterate on each pull request independently, and each one shows only the diff for its layer and the changes between its branch and the branch below it.

The key principle: if code in one layer depends on code in another, the dependency must be in the same branch or a lower one. Create a new branch when you start a different concern that depends on what you've built so far. For example, when you switch from backend to frontend work, move from core logic to tests, or when the current branch is already large enough to review.

Why use GitHub stacked pull requests

Finish one change and move straight onto the next

Stacked pull requests let you open a new pull request on top of one that is still open. During a large project, your next change may depend on work that hasn't merged yet. Instead of waiting for it to merge, with a stack, you can keep building.

With each pull request in a stack containing one focused change, reviewers see a small diff for each layer instead of the large pull request. Smaller pull requests are faster to review, less likely to be skimmed, and less likely to go stale and develop merge conflicts.

Fit for high-volume development

When you generate a lot of code at once, often with AI agents, a stack gives each change a place to go. An agent completes one task, then starts the next task that builds on it. That sequence maps directly onto a stack: one pull request per task, each based on the one below. Stacks let you record those dependencies explicitly instead of combining unrelated changes into a single branch.

Advantages of using stacked pull requests in GitHub

Without stacked pull requests, breaking a large change into smaller, dependent pull requests creates extra work:

• Branch management. Rebasing and keeping branches in sync across dependent pull requests is tedious and error-prone.
• Rules and CI. Branch protection rules and CI checks often only trigger for the bottom pull request in the chain, making it hard to know the true status of the rest.
• Review context. Reviewing a single change out of context from the rest of the stack can reduce review quality.

Stacked pull requests address these problems by treating the chain of pull requests as a connected unit while keeping each layer small and focused.

Rebasing

Rebasing is the trickiest part of working with stacks, and GitHub handles it automatically. You can trigger a server-side cascading rebase from the pull request, or run a local cascading rebase with the gh stack extension in GitHub CLI. When you merge a pull request at the bottom of the stack, the remaining branches are automatically rebased so the next pull request targets the default base branch.