# GitHub Stacked Pull Requests: gh-stack Agent Guide

> Create, submit, sync, review, and merge dependency-ordered PRs with GitHub's preview gh-stack CLI and coding-agent skill.

- **Published**: 2026-07-30
- **Category**: DevOps
- **URL**: https://agentpedia.codes/blog/github-stacked-pull-requests-gh-stack-agent-guide

---

> **Important callout**

**Bottom line:** GitHub stacked pull requests are a public-preview way to review a dependency chain as small PRs. The first-party `gh-stack` extension creates ordered branches, sets each PR base to the layer below, cascades rebases, and can merge through a chosen layer. Verify repository rollout and merge-queue support before making it a required workflow.

[GitHub announced stacked pull requests in public preview](https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-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`](https://github.com/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](/blog/github-copilot-code-review-agent-skills-mcp-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

```text
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:

| Layer | Good content | Bad dependency |
| --- | --- | --- |
| 1. Contract | Types, schema, interfaces | Imports from a higher implementation |
| 2. Service | Logic using the contract | UI-specific workaround |
| 3. Consumer | UI or caller using the service | Changes required by lower API but left here |
| 4. Integration | Cross-layer tests and docs | Hidden production behavior not tested below |

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:

```bash
gh extension install github/gh-stack
```

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

```bash
gh auth status
gh stack --help
```

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

```bash
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:

```bash
gh stack init auth-layer
```

Commit only that concern:

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

Add the next branch from the current top:

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

Add the consumer:

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

Submit the branches and create linked PRs:

```bash
gh stack submit --auto
```

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

```bash
gh stack submit --auto --open
```

Verify the resulting structure:

```bash
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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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](/blog/github-code-quality-ga-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:

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

| Layer | Rollback artifact |
| --- | --- |
| Schema | Backward-compatible migration or documented irreversibility |
| API | Feature flag or compatible prior endpoint |
| Consumer | Disable flag or revertable asset |
| Integration | Deployment and monitoring confirmation |

The [scientific software validation guide](/blog/coding-agents-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:

```text
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:

```text
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.

## FAQ

### Are GitHub stacked pull requests generally available?

No. GitHub announced them as a public preview on July 30, 2026, with repository availability rolling out over days and merge-queue support over subsequent weeks.

### How does gh-stack set pull request bases?

The bottom branch targets the trunk branch, usually main. Each higher pull request targets the branch directly below it, so its review diff shows only that layer.

### Can I merge only part of a stack?

Yes. GitHub documents merging one or more lower layers while upper pull requests remain open and are automatically rebased and retargeted. The CLI can merge through a selected pull request number.

### Does gh stack merge bypass branch protections?

No. The README says bypassing merge requirements is unsupported. GitHub evaluates branch protections and repository rules when the merge runs.

### Is a merge-queued stack one atomic merge?

Not necessarily. The selected pull requests enter the queue together, but the current gh-stack README says the queue may land them in separate groups.


## Official sources

- [GitHub launch: stacked pull requests public preview](https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-in-public-preview/)
- [Official `github/gh-stack` CLI extension and agent skill](https://github.com/github/gh-stack)
- [GitHub REST pull request reference, including stack and asynchronous merge fields](https://docs.github.com/en/rest/pulls/pulls)

---

[Join the Agentpedia newsletter](https://agentpedia.codes/blog)

[Browse related Agentpedia articles](https://agentpedia.codes/blog)


---

- [All articles](https://agentpedia.codes/blog)