Skip to content

Docs site for stacks #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
skarim merged 12 commits into from
Apr 8, 2026
Merged

Docs site for stacks #8

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
214b90e
init docs site
skarim Mar 26, 2026
d5e3c82
add noindex
skarim Mar 26, 2026
a3058ea
clearer examples for init in docs
skarim Mar 27, 2026
c270888
document alias cmd
skarim Mar 29, 2026
3c30dae
updates for latest cmd changes
skarim Apr 3, 2026
3e9f9fd
basic ui walkthrough
skarim Apr 3, 2026
fe887eb
repo housekeeping
skarim Apr 8, 2026
f100cfc
more faq content
skarim Apr 8, 2026
08dc2da
rm test workflow
skarim Apr 8, 2026
8f0d62c
docs cleanup suggestions from code review
skarim Apr 8, 2026
55533a7
rm robots.txt
skarim Apr 8, 2026
b1eb040
fix order of flags and args in cli reference
skarim Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
more faq content
  • Loading branch information
@skarim
skarim committed Apr 8, 2026
commit f100cfcd5e15a4c7bb8ddda32944c7be35c152b6
111 changes: 76 additions & 35 deletions docs/src/content/docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,6 @@ title: FAQ
description: Frequently asked questions about GitHub Stacked PRs.
---

:::note
This FAQ is a work-in-progress. Detailed answers will be added soon.
:::

## Creating Stacked PRs

### What is a stacked PR? How is it different from a regular PR?
Expand All @@ -27,33 +23,59 @@ gh stack add api-routes
gh stack submit
```

Or you can create stacked PRs manually by setting each PR's base branch to the branch of the PR below it.
You can also create stacks entirely from the GitHub UI — create the first PR normally, then when creating subsequent PRs, select the option to add them to a stack. See [Creating a Stack from the UI](/gh-stack/guides/ui/#creating-a-stack-from-the-ui) for a walkthrough.

### How do I add PRs to my stack?

Use `gh stack add <branch-name>` to add a new branch on top of the current stack. When you run `gh stack submit`, a PR is created for each branch and they are linked together as a Stack on GitHub.

You can also add PRs to an existing stack from the GitHub UI. See [Adding to an Existing Stack](/gh-stack/guides/ui/#adding-to-an-existing-stack) for details.

### How can I modify my stack?

Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, you need to delete it and recreate it with the desired order.

### How do I delete my stack?

<!-- TODO: Update once stack deletion workflow is finalized -->

You can unstack a stacked of PRs from the PRs UI on the web. Functionality to do this from the CLI will be coming soon.
You can unstack PRs from the GitHub UI — see [Unstacking](/gh-stack/guides/ui/#unstacking) for a walkthrough. This dissolves the association between PRs, turning them back into standard independent PRs. CLI support for unstacking is coming soon.

### Can stacks be created across forks?

<!-- TODO: Add answer once fork support is confirmed -->

No, stacked PRs currently require all branches to be in the same repository. Cross-fork stacks are not supported.

## Checks, Rules & Requirements

### How are branch protection rules evaluated for stacked PRs?

Every PR in a stack is treated as if it is targeting the **base of the stack** (typically `main`), regardless of which branch it directly targets. This means:

- **Required reviews** are evaluated as if the PR is targeting the stack base.
- **Required status checks** are evaluated as if the PR is targeting the stack base.
- **CODEOWNERS** are evaluated from the stack base — changes in codeowners on a PR at the bottom of the stack will not affect PRs above it in the stack.
- **Code scanning workflows** are evaluated as if the PR is targeting the stack base.

### How do GitHub Actions work with stacked PRs?

GitHub Actions workflows trigger as if each PR in the stack is targeting the base of the stack (e.g., `main`). If you have a workflow configured to run on `pull_request` events targeting `main`, it will run for **every PR in the stack** — not just the bottom one.

### Do all previous PRs need to be passing checks before I can merge?

Yes. In order to merge a PR in the stack, **all PRs below it** must also have passing checks and meet all merge requirements. For example, in a stack of `main <- PR1 <- PR2 <- PR3` and you want to merge PR #3, both PR #1 and PR #2 must have passing checks, required reviews, and satisfy all branch protection rules.

### Is a linear history required?

Yes. There must be a **fully linear history** between each of the branches in the stack. This is a strict requirement for merging.

If the stack is not linear (e.g., after changes were pushed to a lower branch), you can fix it in two ways:

- **From the CLI** — Run `gh stack rebase` to perform a cascading rebase locally and then push with `gh stack push`.
- **From the UI** — Click the **Rebase Stack** button in the merge box to trigger a cascading rebase across all branches in the stack.

## Merging Stacked PRs

### What conditions need to be met for a stacked PR to be mergeable?

The same conditions as any PR targeting the final target branch (e.g., `main`) — required reviews, passing CI checks, CODEOWNER approvals, etc. These rules are evaluated against the final target branch, not the direct base branch of the PR.
Every PR in a stack must meet the same merge requirements as a PR targeting the stack base (e.g., `main`): required reviews, passing CI checks, CODEOWNER approvals, and a linear history. All PRs below it must also meet these requirements. See the [Checks, Rules & Requirements](#checks-rules--requirements) section above for details.

### How does merging a stack of PRs differ from merging a regular PR?

Expand All @@ -65,25 +87,41 @@ You cannot merge a PR in the middle of the stack before the PRs below it are mer

### How does squash merge work?

Squash merges are fully supported. Each PR in the stack produces one clean, squashed commit when merged. The rebase engine automatically detects squash-merged PRs and uses `--onto` mode to correctly replay commits from the remaining branches.
Squash merges are fully supported. Each PR in the stack produces one clean, squashed commit when merged. The rebase engine automatically detects squash-merged PRs and replays commits from the remaining branches onto the squashed result.

### What happens if you close a PR in the middle of the stack?
### How does merge commit work?

<!-- TODO: Add specific behavior details -->
When you merge a stack using the merge commit strategy, it creates **one merge commit for the entire group** of PRs being merged. The full commit history of each PR is preserved within the merge commit.

Closing a PR in the middle of the stack does not automatically affect the other PRs. However, the stack relationship is preserved, so the PRs above the closed PR will still target the closed PR's branch.
### How does rebase merge work?

### What happens when there is an error merging a PR in the middle of a stack?
With rebase merge, all of the commits from each PR in the stack are replayed onto the base branch one at a time, creating a linear history without merge commits.

### Do all PRs get merged at once or one at a time?

PRs in a stack are merged sequentially, from the bottom up. When you initiate a merge, the bottom PR is merged first, and then the next PR above it, and so on.

There will not be a single push operation that adds all the commits from all the branches at once.

### Can I merge only part of a stack? What happens to the remaining unmerged PRs?

Yes, partial stack merges are supported. After the merge, the lowest unmerged PR is updated to explicitly target the stack base (e.g. `main`). A cascading rebase is also automatically run to rebase the remaining unmerged branches.

### What happens if you close a PR in the middle of the stack?

<!-- TODO: Add specific error handling details -->
Closing a PR in the middle of the stack will block all PRs above it from being mergeable. The stack relationship is preserved, so if you want to open a different PR or modify the stack, you will need to unstack and then recreate the stack.

### What happens when there is an error merging a PR in the middle of a stack?

If a merge fails (e.g., due to a failing check or merge conflict), the operation stops and no subsequent PRs are merged. You'll need to resolve the issue before continuing.

### What happens if auto-delete branches is enabled for PRs?
### Does Stacked PRs support merge queue?

<!-- TODO: Add specific behavior details -->
Yes, stacked PRs fully support merging via merge queue. When you merge a stack through the merge queue:

When a PR is merged and its branch is auto-deleted, the remaining stack is rebased so the next PR targets the appropriate base branch.
- **All PRs in the stack are added to the queue** in the correct order, ensuring a linear sequence.
- **If a PR is removed or ejected from the merge queue**, all PRs above it in the stack are also ejected and removed from the queue.
- **Stacks can be split across merge groups** in the merge queue — not all PRs in the stack need to be in the same merge group.

## Local Development

Expand All @@ -101,26 +139,29 @@ See the [CLI Reference](/gh-stack/reference/cli/) for the full command documenta

No. Stacked PRs are built on standard git branches and regular pull requests. You can create and manage them manually with `git` and the GitHub UI. The CLI just makes the workflow much simpler — especially for rebasing, pushing, and creating PRs with the correct base branches.

### Will this work with a different tool for stacking (jj / Sapling / ghstack / git-town, etc.)?
### Will this work with a different tool for stacking?

<!-- TODO: Add compatibility details -->
Yes, you can continue to use your tool of choice (e.g. jj, Sapling, ghstack, git-town, etc.) to manage stacks locally and push up your branches to GitHub.

Stacked PRs on GitHub are based on the standard pull request model — any tool that creates PRs with the correct base branches can work with them. The `gh stack` CLI is purpose-built for the GitHub experience, but other tools that manage branch chains should be compatible.

<!-- ## Miscellaneous -->

<!-- ### Do you have a VS Code extension? -->

<!-- TODO: Add answer -->
You can also use the GitHub CLI in conjunction with other tools to simply create a stack of PRs:

<!-- ### Will stacked PRs work with the GitHub mobile app? -->
```bash
# Create a stack of branches locally using jj
jj new main -m "first change"
jj bookmark create change1 --revision @
# ...

<!-- TODO: Add answer -->
jj new -m "second change"
jj bookmark create change2 --revision @
# ...

<!-- ### Will stacked PRs work with the GitHub Desktop app? -->
jj new -m "third change"
jj bookmark create change3 --revision @
# ...

<!-- TODO: Add answer -->

<!-- ### What happens if I merge via the REST or GraphQL APIs? -->

<!-- TODO: Add answer -->
# Use gh stack to submit a stack of PRs
gh stack init --adopt change1 change2 change3
gh stack submit
```
Loading