GitHub Native Stacked PR Tutorial: How to Use the gh stack Command, How to Merge, and How to Convert Old Branches
GitHub Native Stacked PR Tutorial: How to Use the gh stack Command, How to Merge, and How to Convert Old Branches
First, let's clarify the most common questions searchers have:
- What is this: Stacked PR = split a large change into a series of small PRs with dependent order, each PR contains only the diff for its layer, review layer by layer, and finally merge the entire stack with one click.
- When was it launched: GitHub made it a native feature and opened public preview on July 30, 2026, gradually rolling out to all repositories—before this, you could only simulate it with third-party tools like Graphite, spr, or git-branchless.
- Is it paid: No, it's not a paid plan exclusive feature. The CLI extension
gh-stackis free to install. - Where to use: Supported on github.com web,
ghcommand line, and GitHub mobile; there's also a companion AI agent skill.
1. Five-Minute Quickstart: Building a Stack from Scratch
Prerequisite: Install GitHub CLI (v2.0+, official packages available for Windows/macOS/Linux), then install the official extension:
gh extension install github/gh-stack
Core mental model: a stack is a sequence of ordered branches, each layer built upon the next, with the base layer on the trunk (usually main):
frontend → PR #3 (base: api-endpoints) ← 顶层
api-endpoints → PR #2 (base: auth-layer)
auth-layer → PR #1 (base: main) ← 底层
─────────────
main (trunk)
Complete workflow:
# 1. 建 stack（创建并切到第一个分支）
gh stack init
# ...在第一层提交代码...
# 2. 在上面叠一层
gh stack add api-endpoints
# ...继续提交...
# 3. 推送所有分支
gh stack push
# 4. 查看整个 stack
gh stack view
# 5. 一次性开出整串 PR（每层一个，base 自动指向下一层）
gh stack submit
After submit, GitHub links this series of PRs into a Stack object: each PR page shows a stack map at the top, reviewers can see the current layer's position in the entire change, and each PR only displays the diff for its layer.
A handy trick: gh stack add -Am "Add login endpoint" can complete "stage all changes + commit + auto-generate branch name by date + add new layer" in one command.
2. Review and Merge: The Three Key Rules
- Each layer can be reviewed in parallel. Different colleagues reviewing different layers don't block each other, which is exactly its solution to the pain point of "PRs getting larger in the AI era." In the official announcement, TED's CTO was straightforward: AI made developer output explode, and review became the new bottleneck; splitting large changes into dependent small blocks means "review is not just faster, but more accurate."
- You can merge only a subset. Merging one or several lower layer PRs, the upper PRs will remain open and automatically rebase and redirect the base (e.g., after PR #1 merges into main, PR #2's base automatically changes to main).
- You can also merge the entire stack with one click. Merging the topmost "ready" PR, it and all unmerged layers below will land all at once. Branch protection and required checks still apply, governing what ultimately enters
main.
Merge queue support for stacks will roll out gradually in the weeks after public preview—teams heavily relying on merge queue should confirm their repository is enabled before use.
3. Converting Existing Branches/PRs to a Stack
No need to start over. gh stack init supports adopting existing branches:
# 把两个已存在的分支按顺序收编成一个 stack
gh stack init feature-auth feature-api
# 主干不是 main？指定 trunk
gh stack init --base develop feature-auth
Colleagues' stacks can also be pulled down and continued:
gh stack checkout 42 # 按 PR 号
gh stack checkout <PR URL> # 按 PR 链接
gh stack checkout # 交互式选择器，列出本地+远端所有 stack
4. Daily Maintenance: Rebase and Sync
When the base layer changes or main advances, how do the upper layers follow? Two commands:
# 拉取远端 + 从主干向上逐层级联 rebase
gh stack rebase
# 一条命令完成：拉取、对齐远端 stack、级联 rebase、推送、同步 PR 状态
gh stack sync
In detail, the official implementation is quite thoughtful: init automatically enables git rerere (conflict resolutions are remembered, so rebasing across layers doesn't require resolving the same conflict repeatedly); on rebase conflicts, it prints the conflicted files and line numbers, after resolving and git add, use gh stack rebase --continue, to abort entirely and return to the pre-rebase state use --abort; when a layer's PR has been merged, rebase automatically switches to --onto mode to replay commits correctly.
Stack metadata is stored locally in .git/gh-stack (a JSON file, not committed to the repository).
5. Frequently Asked Questions (FAQ)
Is Stacked PR a paid feature?
No. It's rolling out gradually to all repositories during public preview, and the CLI extension is free.
Can you merge only one PR in a stack?
Yes, but direction matters: merge a lower layer, the upper layers automatically rebase and redirect, staying open; merge an upper layer, all unmerged layers below will land together. To land them one by one, start from the bottommost layer.
Can it be used on Windows?
Yes. gh CLI officially supports Windows/macOS/Linux, and gh-stack is installed cross-platform via gh extension install with consistent command behavior.
Can stacks be created on the web, or must you use the command line?
Officially, stacks can be operated on github.com, CLI, and mobile: the web flow is to create the first PR, then layer branches and PRs on top (each PR's base points to the next layer). The command-line init/add/submit is the most efficient path.
How does it compare to third-party tools like Graphite or spr?
The biggest difference is being native: stack maps are built directly into PR pages, branch protection/required checks/merge queue are officially integrated, and reviewers don't need to install anything. The gaps third-party tools filled for years (cascading rebase, automatic base redirection) are now platform-native behaviors.
Can AI coding agents use it?
An official companion skill is released: gh skill install github/gh-stack, and once installed, your AI agent (e.g., Copilot, Claude Code) knows how to use the full suite of gh stack commands to manage stacked PRs.
When will it officially GA?
No timeline has been announced; it's currently in public preview, and features may change. Feedback channels are the official stacks discussion (gh.io/stacks-feedback).