astradevlabsastradevlabs
← All posts
Dev Tips5 min

Step-by-Step Playbook: Ship AI-Sized Changes With GitHub's New Stacked PRs

Dev Tips

GitHub dropped two changes on July 30, 2026 that fit together better than they first appear: stacked pull requests entered public preview, and GitHub Actions gained $/ self-repository syntax for actions and reusable workflows. If your team is suddenly producing bigger diffs because AI tools make code generation cheap, those two updates are a practical answer to the new review bottleneck.

This playbook is for the case where one task is real work, but one pull request would be too noisy: a migration, a refactor, a broad UI sweep, or an agent-assisted cleanup. The goal is simple: split the work into reviewable layers without turning your branch management and CI wiring into a second project.

1. Start with one trunk branch and one real bottom layer

GitHub's stacked PR model is built around dependent layers. The bottom PR targets main, the next PR targets the branch below it, and so on. That sounds obvious, but the practical rule is stricter: your first layer must be independently understandable.

Good first layers look like:

  • rename and move files without logic changes
  • add a compatibility shim or shared adapter
  • introduce tests or fixtures that later layers will rely on

Bad first layers mix mechanical cleanup with behavior changes. If reviewers cannot approve the bottom layer without reading the whole future stack, you did not really split the work.

2. Create the stack with the official CLI extension

GitHub's public preview ships with the gh-stack CLI extension. The minimal setup is still the best one:

bash
gh extension install github/gh-stack
gh stack init
# make the first focused change and commit it
gh stack add api-cleanup
# make the next change and commit it
gh stack push
gh stack submit

The key benefit is not that it creates branches for you. The real win is that it keeps base branches correct, so each PR shows only the diff for that layer. That is the part that makes stacked review usable instead of annoying.

3. Keep each layer review-sized, not task-sized

GitHub's launch post is explicit about the value proposition: review each layer independently, and merge one, some, or all of the stack when ready. That only works if each PR is narrow enough that a reviewer can say yes or no without reconstructing the whole project in their head.

A useful limit is one concern per PR:

  1. structure layer: file moves, extraction, dead-code cleanup
  2. contract layer: types, interfaces, API shapes, shared helpers
  3. behavior layer: actual feature or migration logic
  4. polish layer: docs, follow-up cleanup, UI copy, or telemetry

That order matters because feedback on lower layers can cascade upward cleanly. If you bury behavior changes in the base of the stack, every later rebase becomes expensive.

4. Fix your Actions references before CI becomes the bottleneck

The quiet companion change from July 30 is the new $/ syntax for same-repository actions and reusable workflows. GitHub says it resolves against the running workflow's repository at the exact commit being executed, with no checkout required, and it is now the recommended path for internal action references.

That matters for stacks because dependent PRs tend to exercise internal workflows constantly. Old ./ references work, but they depend on workspace checkout and are awkward when you want consistent SHA-pinned behavior across a chain of PRs. The new syntax is cleaner:

yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: $/.github/actions/setup-node-pnpm
      - uses: $/.github/actions/lint-web

Two details are easy to miss:

  • it works for reusable workflows and composite actions, not just one local action
  • it requires GitHub Actions runner version 2.336.0 or newer

If your organization is enforcing full-length SHA pinning, this is the upgrade that stops same-repo reuse from fighting your policy.

5. Use AI sessions to create layers, not giant PRs

The most honest part of GitHub's companion Copilot app write-up is the warning about scope creep. Once an agent can produce code quickly, the temptation is to let one session sprawl into a massive pull request. Stacks are most valuable when they are a forcing function against that behavior.

A practical prompt pattern is:

Make the current migration a first pull request off main. Then start a second branch on top for the follow-up cleanup, and keep it as a separate pull request.

That keeps the agent productive while preserving human review boundaries. Think of stacked PRs as a review control system, not just a branching feature.

6. Merge from the bottom, and let the top stay draft longer

GitHub's docs emphasize bottom-up merging and CI optimization for stacks. In practice, that means you should resist the urge to mark the whole stack ready at once. Land the bottom layer as soon as it is solid. Keep experimental or cleanup layers above it in draft until the base is stable.

That gives you three wins:

  • reviewers see smaller diffs
  • merge queue behavior stays predictable
  • failed checks isolate to one layer instead of contaminating a monster PR

If your team is adopting AI coding faster than it is improving code review, this is the simplest workflow adjustment worth making this month.

References