GitHub Native Stacked PRs (gh stack)

GitHub has a first-party stacked-PR model: a chain of PRs registered with GitHub, driven by the github/gh-stack CLI extension. A registered stack behaves differently from the ad-hoc chain this plugin's other skills describe — GitHub retargets, runs CI, and merges the stack itself.

Public preview. The feature and its CLI surface are subject to change. No repository or organization setting enables it; it is on by default.

When to Use This Skill

Registered stack vs. ad-hoc chain

Three hazards this plugin documents at length apply to ad-hoc chains (you opened PR B with --base pointing at PR A's branch). A stack registered with GitHub removes all three:

Required reviews, required status checks, and CODEOWNERS are enforced against the stack's base branch for every PR in the stack — a stack is not a way to route around branch protection.

Ad-hoc chains remain the right tool where a stack cannot go: cross-fork work, and any repo where the merge tooling has not been updated (see Limits).

Setup

gh --version                                # need 2.90.0+ (git 2.20+)
gh extension install github/gh-stack
gh stack alias                              # optional; creates `gs`

Lifecycle

gh stack init                               # start a stack; -b <branch> to set trunk
git add . && git commit -m "feat(a): first layer"

gh stack add feat/layer-b                   # next branch on top
git add . && git commit -m "feat(b): second layer"
# or in one step:
gh stack add -Am "feat(b): second layer"    # -A stages all incl. untracked; -u tracked only

gh stack push                               # push every branch in the stack
gh stack submit                             # create/update the linked PRs
gh stack view                               # ordering + PR links (-s short, --json)

gh stack submit opens an editor and creates drafts by default. For non-interactive agent use:

gh stack submit --auto --open               # auto-generated titles, ready for review

Because --auto generates titles from commits, the commit subjects must already be conventional (.claude/rules/conventional-commits.md) — a PR title is what lands on squash-merge.

Keeping the stack current

gh stack sync                               # fetch + rebase + push + refresh PR state
gh stack sync --prune                       # also delete branches of merged PRs
gh stack rebase                             # cascading rebase only
gh stack rebase --downstack                 # trunk → current branch only
gh stack rebase --upstack                   # current branch → top only
gh stack rebase --continue | --abort        # after resolving conflicts

Conflicts exit 3; resolve, then --continue. --abort restores the pre-rebase state.

Navigating and restructuring

gh stack modify and gh stack switch are TTY-interactive — unusable from an agent's Bash tool. Reach for gh stack rebase/link/view --json instead.

gh stack link is the migration path for an ad-hoc chain that already exists: it converts the manual chain into a registered stack, which is what buys the auto-retarget and CI behaviour above.

Merging

gh stack merge <stack-no | pr-no> --squash -y

Merge methods: --merge, --squash, --rebase (or --merge-method <m>). -y skips the confirmation prompt. PRs merge bottom-to-top; merging a mid-stack PR leaves the ones above open and retargeted.

Limits

The merge-API limit is the one that bites automation: audit any bot, just recipe, or workflow that merges PRs programmatically before adopting stacks in a repo, or those merges will start failing on stacked PRs only.

Exit codes

gh stack exits with specific codes — branch on them rather than parsing text.

Code 8 (locked by another process) is the stack-level analogue of .claude/rules/agent-coworker-detection.md: another agent or session is operating on the same stack. Back off; do not force.

Agentic Optimizations

gh stack view --json exits 0 with valid JSON on an empty result, so it is parallel-safe (.claude/rules/parallel-safe-queries.md); the bare gh stack view exits 2 outside a stack and would cancel sibling calls in a batch.

Quick Reference

Related

• git-plugin:git-merge-hazards — auto-close, push-by-SHA races on ad-hoc chains
• git-plugin:git-rebase-patterns — git rebase --update-refs, the local-only equivalent of gh stack rebase
• git-plugin:git-pr — single-PR creation and the manual retarget/rebase dance
• .claude/rules/gh-json-fields.md — state/mergedAt when auditing a stack's PRs
• .claude/rules/conventional-commits.md — why --auto titles depend on commit subjects