GitHub Stacked Pull Requests: gh-stack Agent Guide

GitHub announced stacked pull requests in public preview on July 30, 2026. The feature preserves ordinary reviews, checks, branch protections, and merge requirements while adding a stack map and coordinated merging. GitHub is rolling repository availability out over days and merge-queue support over subsequent weeks.

The first-party github/gh-stack CLI extension and its agent skill automate the branch and PR mechanics. They do not decide how to split a change, prove an upper layer is safe, or guarantee that preview behavior will remain unchanged.

What GitHub previewed

A stack is an ordered series of pull requests. Each PR is a focused layer, and each higher layer depends on the ones below it. Reviewers can work on layers in parallel, while GitHub keeps the dependency relationship visible.

GitHub documents three main benefits:

• review narrow diffs instead of one large combined change;
• retain existing checks and branch protections for every layer;
• merge one, some, or all layers.

This is especially useful for coding-agent output. An agent can produce a large coherent feature quickly, but a reviewer still needs comprehensible trust boundaries. A stack can separate a data model, API, UI, and integration tests without pretending those PRs are independent.

The Copilot skills and MCP review guide explains how to customize automated review. Stacks solve a different problem: structuring the change so both humans and review tools see the right diff.

Use the dependency chain as the mental model

main
└── auth-layer          PR #1, base: main
    └── api-endpoints   PR #2, base: auth-layer
        └── frontend    PR #3, base: api-endpoints

The bottom branch is closest to trunk. The top branch is furthest away. A review of PR #2 compares api-endpoints with auth-layer, so the auth diff is not repeated. The combined top branch still contains all lower work in its history.

Put foundations below consumers:

Each layer should compile or pass the checks that are meaningful at that point. If a layer cannot work without a later PR, state that explicitly and avoid presenting it as independently deployable.

Install the CLI and agent skill

Install the GitHub CLI extension:

gh extension install github/gh-stack

The README requires GitHub CLI 2.0 or newer. Verify authentication and discover the commands:

gh auth status
gh stack --help

Install the first-party skill so a compatible coding agent knows the workflow:

gh skill install github/gh-stack

Inspect the skill before use. Its current rules tell agents to use non-interactive arguments, plan dependency order first, stage deliberately, run submit --auto, inspect view --json, and merge with --yes. Those conventions prevent a terminal agent from hanging in a TUI and preserve layer boundaries.

An installed skill guides the coding agent; it does not grant permission to create branches, push, submit PRs, or merge. Those remain separate repository-changing actions requiring user authorization.

Create and submit a stack

Plan branch names and boundaries before moving files. Then create the bottom layer:

gh stack init auth-layer

Commit only that concern:

git add src/auth tests/auth
git commit -m "Add authentication boundary"

Add the next branch from the current top:

gh stack add api-endpoints
git add src/api tests/api
git commit -m "Add authenticated API endpoints"

Add the consumer:

gh stack add frontend
git add src/ui tests/ui
git commit -m "Add account interface"

Submit the branches and create linked PRs:

gh stack submit --auto

With --auto, new PRs are drafts unless --open is supplied:

gh stack submit --auto --open

Verify the resulting structure:

gh stack view --json

Check that:

• the bottom PR targets trunk;
• each upper PR targets the branch below;
• titles and descriptions identify the layer;
• no file appears in a layer where its dependency does not belong;
• each PR has expected reviewers, labels, and checks.

gh stack push only pushes active branches. It does not create or update PRs; use submit for that. The README also warns that a multi-branch push is not atomic: branches whose force-with-lease checks pass may update even when another branch is rejected.

Respond to review and synchronize safely

When review finds a defect in a lower layer, change that layer rather than patching around it at the top:

gh stack bottom
# edit, test, stage, and commit the lower-layer fix
gh stack rebase --upstack
gh stack push

gh stack rebase cascades from trunk upward so every branch contains the updated parent. If conflicts occur:

# resolve conflicts and stage the files
gh stack rebase --continue

# or restore all branches to their pre-rebase state
gh stack rebase --abort

For routine synchronization:

gh stack sync

The documented sequence fetches, reconciles the remote stack, fast-forwards trunk when possible, cascades a rebase if trunk moved, pushes, synchronizes PR state, links the remote stack, and optionally prunes merged branches.

In a non-interactive environment, use:

gh stack sync --prune

Only add --prune when deleting local branches for merged PRs is intended. Without it, branch cleanup can remain a separate reviewable step.

The GitHub Code Quality guide is useful here: every layer keeps its own review and checks, so coverage and deterministic findings should be evaluated at the PR where the behavior appears.

Merge all or part of a stack

The CLI documents three exact merge scopes:

# Whole current stack
gh stack merge --yes

# Remote stack by stack number
gh stack merge 7 --yes

# Bottom through PR #42
gh stack merge 42 --yes

For direct merging, all selected members through the chosen PR are an all-or-nothing operation: if any cannot merge, none merge. You can request a method:

gh stack merge --yes --squash

GitHub evaluates branch protection and repository rules during the merge. gh-stack does not support bypassing merge requirements.

The launch post says merging a lower part leaves higher PRs open and automatically rebases and retargets them. Verify the resulting bases and diffs after any partial merge:

gh stack sync
gh stack view --json

Run the checks again on upper layers. A rebase changes commit identities and can change the effective combined diff even when a layer's source files appear untouched.

Treat merge queues as staged preview behavior

Merge-queue support is not assumed available everywhere. GitHub says it is rolling out progressively over weeks after the July 30 preview.

When the base uses a merge queue, gh stack merge adds the selected PRs to the queue rather than merging directly. The queue chooses the merge method, so a CLI merge-method flag is ignored with a warning.

Most importantly, the current README says selected PRs are added together but may land in separate groups as the queue processes them. Do not describe that path as one atomic merge. Monitor each PR and the stack after queue processing:

gh stack view --json
gh pr checks PR_NUMBER

Design layers so the repository remains valid after each possible landed group. If that is impossible, do not rely on staged queue support for that stack.

Know what recovery is documented

gh-stack provides reversible local operations before merge:

• gh stack rebase --abort restores branches to pre-rebase state;
• gh stack modify --abort restores a restructuring session;
• force-with-lease protects pushes against unexpected remote movement;
• gh stack unstack --local removes local tracking without deleting the GitHub stack.

The launch and README do not promise a one-command rollback for already merged application changes. Once a layer reaches trunk, use the repository's ordinary revert, rollback, or forward-fix procedure. Record which PRs landed and in what order before starting recovery.

gh stack modify can drop, fold, insert, rename, and reorder branches, but it requires a clean, linear history and no queued PR. Its “drop” operation removes a branch from the stack structure while preserving the local branch and associated PR. Run gh stack submit afterward to reflect the new structure on GitHub.

For high-risk changes, define rollback per layer:

The scientific software validation guide makes the same general point: reviewable changes still need an external acceptance target and an owned recovery path.

Give coding agents a bounded workflow

A useful agent request names the stack but keeps decisions reviewable:

Plan a three-layer stack for this feature:
1. shared contract,
2. API implementation,
3. UI consumer.

Do not create branches yet. Show the file allocation, dependency order,
tests per layer, and commands you would run. Stop before push, submit, or merge.

After approval, authorize only the next mutation:

Create the three local stack branches with gh-stack and commit the reviewed
file groups. Run tests per layer and return gh stack view --json.
Do not push or create pull requests.

Push, PR creation, and merge can each be separate checkpoints. This makes the agent skill useful without allowing workflow convenience to erase repository authority.

For non-interactive agent execution, use explicit branch names, gh stack submit --auto, gh stack view --json, and gh stack merge --yes only when the merge itself has been authorized. Configure remote.pushDefault or pass --remote where supported if the repository has multiple remotes.

Verify every transition

Before submit:

• repository preview availability is confirmed;
• each branch has one coherent concern;
• dependencies point downward;
• working tree and tests are clean at each layer;
• gh stack view --json reports the expected order.

After submit:

• each PR base is correct;
• each diff excludes lower-layer changes;
• required reviewers and checks are present;
• branch protection applies to the trunk path;
• stack UI is visible in the enabled repository.

Before merge:

• selected PRs are open and not drafts;
• every selected layer has approvals and passing requirements;
• upper layers remain compatible with a partial merge;
• merge-queue support is confirmed if required;
• rollback artifacts exist per layer.

After merge:

• inspect actual landed groups and order;
• run gh stack sync and verify retargeted upper PRs;
• rerun upper checks;
• monitor deployment and business invariants;
• prune branches only after state is understood.

Practical verdict

Use stacked PRs for one cohesive change whose layers have a real dependency order and distinct review surfaces. They are particularly helpful when coding agents produce changes faster than humans can safely review one combined diff.

Do not use a stack to disguise unrelated work or to avoid making each intermediate repository state valid. Because the feature and merge-queue integration are previews with progressive rollout, keep an ordinary branch-and-PR fallback until availability and behavior are verified in every required repository.

Official sources

• GitHub launch: stacked pull requests public preview
• Official github/gh-stack CLI extension and agent skill
• GitHub REST pull request reference, including stack and asynchronous merge fields