Home

I tried stacked pull requests on my own portfolio

July 30, 2026

GitHub just announced stacked pull requests in public preview. Instead of reading the changelog and moving on, I decided to actually try it on this same portfolio repo.

The problem it solves

I've done the manual version of this before: branch off a big feature, realize it's too large to review in one shot, and split it into a chain of branches that each target the previous one. It works, but every rebase is manual, and if the bottom branch changes, you're rebasing the whole chain by hand.

Stacked PRs formalize that pattern:

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

Each PR only shows the diff for its own layer. Merge the bottom PR and GitHub automatically retargets the one above it to main. The key rule: if a layer depends on code from another layer, that dependency has to live in the same branch or a lower one.

Setting it up

GitHub ships a CLI extension for the local workflow:

sh
1gh extension install github/gh-stack

It needs gh ≥ 2.90.0, and my local gh was still on 2.83.2, so an upgrade came first. Once that was sorted, starting a stack looks like this:

sh
1gh stack init blog-stacked-prs-scaffold
2# ... write code, then:
3gh stack add -Am "feat: scaffold blog post about stacked pull requests"

gh stack add either commits to the current branch (if it has no commits yet) or creates a new branch on top of the stack, depending on where you are. That's exactly the mechanic I used to write this post: this section you're reading is its own layer, sitting on top of the scaffold layer that added the post's metadata and title.

What I actually stacked

For this post I split the work into three layers instead of one big commit:

  1. Scaffold — the entry in data/blog-post.ts and the skeleton page.mdx with just the title and intro.
  2. Content — this section, the actual body of the post.
  3. Closing — conclusion and cleanup.

It's a small example, but it maps to the real reason I'd reach for this on a bigger change: shared types or data first, the logic that depends on them next, and UI last. Each layer becomes a PR that's small enough to actually review carefully instead of skimming a 40-file diff.

What I'd watch out for

Stacked PRs aren't free. A few things worth keeping in mind:

  • Ordering discipline matters. If you put a dependency in the wrong layer, you'll notice fast: the PR below won't build, or the one above will show changes that don't belong to it.
  • It's a solo-repo-friendly workflow too. I don't have reviewers on this portfolio, but splitting the work still forced me to think in terms of "what does this layer actually depend on," which is the same discipline that makes stacks worth it on a team.
  • Cross-fork stacks aren't supported. Everything has to live in the same repository, so this doesn't help for external contributions to a project you don't have write access to.

Conclusion

The manual version of this — chained branches, hand rebasing — always worked, but it was tedious enough that I'd only bother for genuinely large changes. gh stack removes enough of that friction that I'd consider using it for something as small as this post. The mechanism is simple: each layer is a branch, each branch is a PR, and the tool keeps the base branches in sync as the stack changes underneath.

Next time I have a change that's too big for one clean review, I know exactly where to start.

Docs: Stacked pull requests · Extension: github/gh-stack