GitHub Stacked Pull Requests for Coding Agents

Use GitHub stacked pull requests to review dependent coding-agent changes, recover from a failed middle layer, and keep merge order explicit.

Three dependent pull-request layers, with a failed middle layer repaired before the upper layer advances.

GitHub stacked pull requests organize dependent code changes as an ordered chain of small pull requests instead of one oversized change. For parallel coding agents, the useful part is not simply smaller diffs: the stack records which layer depends on which, gives reviewers a bottom-up order, and provides a recovery path when a middle change fails. GitHub remains authoritative for branches, pull requests, and merges, while the CI system owns its checks; the team still needs explicit ownership, acceptance criteria, and human review.

What are GitHub stacked pull requests?

A GitHub stacked pull request is one layer in a chain of dependent pull requests. The bottom pull request targets the trunk branch, usually main. Every pull request above it targets the branch directly below. Each reviewer sees the diff for one layer, while the branch ancestry preserves the order in which the changes depend on one another.

The structure looks like this:

main
  └── state-layer   → PR 1, base: main
        └── policy-layer → PR 2, base: state-layer
              └── client-layer → PR 3, base: policy-layer

This is not three unrelated pull requests that happen to belong to one feature. The client layer is meaningful only after the policy layer, and the policy layer depends on the state layer. GitHub's stacked pull request overview describes the same core rule: a dependency must live in the same branch or a lower branch.

That distinction matters when coding agents are involved. Agents can produce branches quickly, but a stack does not make dependent work independent. It makes the dependency visible. If the contract between layers is unsettled, keep that work sequential. Use parallel agents for stable adjacent work, tests, review, or genuinely separate areas, then place each dependent deliverable in the correct layer.

When should coding agents use stacked PRs?

Use a stack when one coherent change can be divided into reviewable layers and each upper layer genuinely requires the one below. Avoid a stack when the work is unrelated, when every change can target main independently, or when the dependency chain is so volatile that every lower edit would continuously rewrite the layers above it.

Situation Better workflow Why
Shared type, then API, then client Stacked pull requests The dependency order is real and each layer can have a focused diff
Three unrelated fixes Independent pull requests There is no useful dependency chain to encode
Two agents editing the same unstable interface One owner first, then a handoff A stack records branch order but does not resolve an undecided contract
Large feature with a stable foundation and separable layers A short stack Review can begin on lower layers while upper work continues
Many approved changes competing to enter main Merge queue The problem is final integration order, not review-layer dependency

Keep the stack shallow enough that a change near the bottom does not create an unmanageable cascade. There is no universal safe depth. The right limit depends on how often lower layers change, how expensive revalidation is, and whether one person can still explain the whole chain.

For the broader coordination decision, our agent orchestration guide explains when work is truly parallel and when dependency order should keep it sequential.

How do you create a GitHub stacked PR workflow?

Start by defining the dependency chain before creating branches. Give each layer one purpose, one owner, and one acceptance check. Then use GitHub's stack-aware tooling to create branches in that order. The stack should reflect the engineering dependency, not the order in which agents happened to finish.

GitHub's current quickstart lists GitHub CLI 2.90.0 or later and Git 2.20 or later as prerequisites. The following is an illustrative three-layer sequence adapted from that guide:

gh extension install github/gh-stack

gh stack init state-layer
  # Edit the state contract.
git add .
git commit -m "Add state contract"

gh stack add policy-layer
  # Add policy that depends on the state contract.
git add .
git commit -m "Add retry policy"

gh stack add client-layer
  # Add the client that consumes both lower layers.
git add .
git commit -m "Add policy client"

gh stack submit
gh stack view

gh stack submit pushes the branches, opens the pull requests with the correct base branches, and links them as a stack. The first pull request targets the trunk. Each later pull request targets the branch below it. Reviewers therefore see only the change introduced by the current layer.

You can also form a stack in the GitHub web interface by choosing the previous pull request's branch as the next pull request's base. The official creation guide notes that all branches must be in the same repository; cross-fork stacks are not supported.

Before submission, record five things where every contributor can see them:

  1. the trunk and ordered branch names;
  2. the owner of each layer;
  3. the contract each layer exports to the one above;
  4. the required check for each pull request and for the combined result;
  5. the person who decides whether a failure requires a fix, a reorder, or a smaller stack.

Those details prevent a common failure: Git knows the ancestry, but nobody knows who should respond when the middle layer changes.

What did our failed-middle experiment show?

In our deterministic local Git fixture, a three-layer stack exposed the true middle-layer policy failure with less recovery work than three independent branches. The stacked condition used five validation runs, one rebase, and four documented recovery steps. The independent condition used six validations, two rebases, and six recovery steps.

The fixture contained three changes:

  • a state layer that defined shared configuration;
  • a policy layer that depended on that state but set a retry budget of 18, above the fixture's allowed maximum of 16;
  • a client layer that depended on both lower layers.

The independent branches initially failed for missing dependencies. Only after rebasing the policy branch onto the state branch did the actual invalid retry budget appear. The client then needed another dependency rebase. In the stacked condition, ancestry already encoded both dependencies, so the policy failure appeared in its real context.

Observed measure in this fixture Stacked branches Independent branches
Validation runs 5 6
Rebases 1 2
Documented recovery steps 4 6
Review order encoded before recovery Yes No
Fast-forward merge commands 3 3

In this fixture only, the independent workflow required one additional validation and one additional rebase. That is information about this dependency chain, not a claim that stacks always save a fixed amount of work.

The test did not use GitHub's pull request UI or API. It did not measure coding-agent quality or speed, human review time, hosted CI or network latency, or production merge throughput. It also did not prove that a stack is better for unrelated changes. Its narrow result is that branch ancestry preserved the intended dependency order and shortened recovery for one deliberately broken middle layer.

That control condition is the gap in most current explanations. GitHub's documentation explains the mechanics. An independent two-layer GitHub experiment usefully shows rebasing after the bottom branch changes. Our fixture adds a three-layer failure, an independent-branch comparison, and explicit recovery counts.

How do you recover when a middle stacked PR fails?

Fix the defect in the middle branch, then cascade that corrected history through every layer above it and rerun the affected checks. Do not patch around the failure in the top branch. That hides the true ownership of the fix and leaves the dependency chain harder to review.

A practical recovery sequence is:

  1. Stop treating upper layers as ready, even if their own diffs look reasonable.
  2. Check out the failing middle branch and make the smallest correction there.
  3. Commit the correction with its acceptance evidence.
  4. Rebase the branches above onto the corrected middle layer.
  5. Push the rewritten branches and rerun checks for every affected pull request.
  6. Resume review from the lowest changed layer upward.

GitHub's stack management guide documents the CLI sequence for a lower-layer fix:

gh stack checkout policy-layer
  # Apply and commit the fix in the layer that owns it.
git add .
git commit -m "Fix retry policy"

gh stack rebase --upstack
gh stack push
gh stack top

If the rebase stops on a conflict, resolve the affected files, stage them, and continue with gh stack rebase --continue. Use gh stack rebase --abort when the attempted cascade should be discarded and retried from the pre-rebase state.

Force-pushed stack branches are shared state. Before cascading a lower-layer change, make sure another person or agent is not still building on an old tip. A branch can be mechanically correct and still surprise a worker whose local checkout has become stale.

How should teams review a stack from coding agents?

Review a stack from the bottom upward, because every upper diff assumes the contracts below it. Check each pull request as a focused change, then check the stack as a connected system. Automated review can add evidence, but a named person still owns requirements, tradeoffs, and the decision to merge.

Use the following review pass for each layer:

  1. Dependency: Does the pull request depend only on the branch below, or did it reach sideways into another unfinished change?
  2. Scope: Does its diff contain one explainable concern, or did an agent bundle unrelated cleanup into it?
  3. Contract: Is the interface consumed by the next layer stable and tested?
  4. Evidence: Did the layer's deterministic checks run on the exact commit under review?
  5. Handoff: Does the next owner know which commit, assumptions, and unresolved risks they inherited?

Then run a stack-level pass. Verify the combined behavior, branch protection, required checks, and merge method. GitHub made native stacks generally available with stack navigation, cascading rebases, automation surfaces, and merge-queue integration, but those mechanics cannot decide whether the layered design satisfies your product requirement.

If your team uses an AI reviewer, treat its findings as another input rather than the merge authority. Our Claude Code Review guide separates automated PR findings from deterministic tests and accountable human approval.

Stacked PRs, worktrees, and merge queues solve different problems

These controls are complementary. Worktrees isolate files while people or agents edit. Stacked pull requests express dependency order during review. A merge queue verifies an approved change against the latest combined state before it lands. Substituting one for another leaves a different risk uncovered.

Control Primary question What it does not prove
Git worktree Where can this worker edit without sharing a working directory? That two branches are compatible or correctly ordered
Stacked pull requests Which review layer depends on which lower layer? That the final combined state passes every integration requirement
Merge queue Does this approved change pass against the current integration state? That its dependency decomposition or human review was sound
Shared coordination record Who owns each layer, file, handoff, and decision? That Git history, CI, or GitHub policy is correct

Our Git worktree versus branch guide covers editing isolation. Our merge queue guide for coding-agent pull requests covers combined-state checks after review. A team running several agents often needs all three controls: one workspace per worker, an explicit stack for dependent review, and a final integration gate.

Where does SyncStaff fit in a stacked PR workflow?

SyncStaff can hold the shared record around the GitHub stack: work intent, task dependencies, current ownership, file leases, handoffs, and human decisions. Git and GitHub remain authoritative for branches and pull requests. Your CI provider runs the checks. SyncStaff does not create, rebase, validate, merge, or guarantee a stack.

A concrete handoff might say: the state layer is accepted at one commit; the policy owner may proceed; the client layer must wait for a named policy check; and a person must decide if a retry-budget change alters the product requirement. That record is useful when the agents run in different tools or sessions and cannot rely on one chat history.

Before submitting a stack produced by several coding agents, declare each layer's intent, dependency, file scope, and acceptance check. Reserve shared files where your client supports that workflow, record the handoff when a lower layer changes, and keep the final merge decision with a person. Then let gh stack, GitHub, and CI handle the code state they actually own.

Frequently asked questions

What is a stacked pull request on GitHub?

A stacked pull request is one layer in an ordered chain of dependent pull requests. The bottom pull request targets the trunk branch, while each higher pull request targets the branch below it. Reviewers see a focused diff for each layer, and the branch ancestry records dependency order.

Do GitHub stacked pull requests have to use one repository?

Yes. GitHub's current stacked-pull-request documentation requires every branch in a stack to live in the same repository; cross-fork stacks are not supported. The trunk can be the default branch or another branch, but every higher pull request must target the branch directly below it.

Can several coding agents work on the same PR stack?

They can, but the stack does not make dependent work safely parallel by itself. Give each layer a named owner, stable input contract, acceptance check, and explicit handoff. If two agents need to change the same unsettled interface, establish one owner and sequence that decision before building upper layers.

Do stacked PRs reduce CI runs?

Not automatically. A lower-layer change can trigger new checks on every affected layer above it. In our synthetic three-layer fixture, the stack used five validation runs versus six for independent branches, but that one-run difference is not a production CI forecast. Measure your own workflow and optimize only with reliable dependency evidence.

Do stacked pull requests replace a merge queue?

No. A stack expresses dependency and review order among pull requests. A merge queue tests approved work against the latest combined integration state before it lands. GitHub can connect the two workflows, but teams still need layer-level review, deterministic checks, branch policy, and accountable human approval.