Stacked pull requests are now in public preview 🚀

[ebndev]

Stacked pull requests break large changes into small, reviewable pull requests. They're an ordered series of pull requests that each represent focused layers of your change. With stacks, you can independently review and check each pull request, then merge everything together in one click. No more opening a single large pull request that takes forever to review, or splitting work across multiple branches you have to keep manually rebasing.

"We've been using GitHub stacked PRs for Next.js for the past few months. It has helped us introduce smaller individual changes while shipping larger features, making it easier to review PRs. - Tim Neutkens, NextJS lead, Vercel"

072926-gitub-tmp-pr-v08.mp4

With stacked pull requests, teams can:

• Keep large changes moving by reviewing short, narrowly scoped pull requests in parallel.
• Maintain quality across every layer by using focused pull request reviews alongside existing branch protections to protect main.
• Merge one, some, or all by landing an entire stack altogether or individual layers one at a time.

And because stacked pull requests are built into GitHub, your existing reviews, checks, and merge requirements all work out of the box.

"The new Github Stacked PRs preview is incredible. Landing 5 stacked PRs directly to a merge queue all at once! A+++! This removes so much friction (and the gh cli tools + agent skill help a ton)" - John Resig, creator, jQuery

Get started with the CLI extension

Install the CLI extension and create your first stack in under a minute:

gh extension install github/gh-stack

Create stacks from your terminal or github.com

Create a stack from github.com, the GitHub CLI, the GitHub mobile app, or with a coding agent such as GitHub Copilot using the gh-stack skill. Start with a branch and pull request for your first change. Then add branches and pull requests on top of it; each pull request targets the layer below it.

Stacks-Changelog-InLine-01-CLI.mp4

Review each layer independently

Open any pull request in the stack to review only the diff for that specific layer. Use the stack map at the top of the pull request to see how the change you're reviewing fits into the larger work. You and your teammates can each review different layers in parallel without blocking further work.

"AI has made TED's developers dramatically more productive, but that created a new bottleneck: PRs were growing large enough that reviewers were struggling. Stacked PRs help to solve that. By breaking large changes into small, dependency-ordered pieces, review happens in smaller logical chunks - not just faster PR reviews, but more accurate ones. Stacked PRs tighten our feedback loop and help get stable code to ted.com faster." - Andy Merryman, CTO, TED

Merge everything in a single click

Merge the latest ready pull request to land it and every unmerged layer below it in one single operation. To land part of a stack, merge one or more lower layers—the pull requests above it stay open and automatically rebase and retarget. Your existing branch protections and required checks still govern what reaches main.

"A big change used to mean one giant PR nobody wanted to review. Now it's a stack of small ones reviewers can actually follow, and the whole stack merges in one shot. It stopped feeling like a tool on top of GitHub and started feeling like GitHub." - Mayank Saini, connectivity engineer, WHOOP

Stacks-Changelog-InLine-03-MergeBox.mp4

Find out more and share your feedback

Stacked pull requests are rolling out in public preview to all repositories over the coming days. Merge queue support for stacked pull requests is rolling out progressively over the coming weeks.

For more information, check out the stacked pull requests documentation, and share your feedback with us in the comments below!

[AnupRajput1234]

gh extension install github/gh-stack

[ebndev]

Hey @AnupRajput1234,

To get started, you can run this command in the GitHub CLI 😄

[jens-gilion]

My claude code workflow would love if the CLI allowed merging stacks as well.

Further, when the stack requires a rebase, the "merge" button is still green and seems to attempt a merge that will inevitably fail, this is rather frustrating as it takes quite some time for the UI to reflect this

[jcaudill-truepic]

Please show the PR approvals on the stack list and merge stack list!

[victorDigital]

And gh actions status also! 🙌

[imanmahjoubi]

Thank you for sharing your thoughts! We do show the "ready" status in the merge box. Are you referring to something else or you are asking to add the status to all the stacks views?

[justinoboyle]

We do show the "ready" status in the merge box. Are you referring to something else or you are asking to add the status to all the stacks views?

Ready implies to me more of a status check then the approval status - a small indicator that it has been approved separate from required status checks would be helpful! (e.g. "Approved but required CI failing" is a different piece of information than "Waiting for approval, but all the checks are good to go")

[alvis]

It's what I'm looking for too. I have stacks of dozen of PRs and some PR have approved and some are not. It's really hard to tell from the list atm

[fgr-17]

+1 yes totally. Also showing CI status completion would be great

[felixminom]

Idk if I did something wrong, but I did merge PR2 and then PR1 and only got PR1 merged to main. I had to merge main into PR2 and solve conflicts to be able to merge that one as well. In any case, I think it's not very intuitive what's going on; this was my structure:

• main
  • PR1
    • PR2

[daprezjer]

Something similar here. I merged the PR1 into main (which i thought i'd have to do first), and then when I went to merge in PR2, it says "stack conditions not met" and I can't merge. No indication of what exactly that condition is. Guess I did something in the wrong order, but it's not obvious which order to do things in.

[daprezjer]

Turned out that the conditions that weren't met were just my standard blocking tests not having run yet. The tooltip was just confusing since it referenced the stack, when it was really just that ticket.

[theophanemayaud]

Yeah same, seems buggy !

[benjaminclauss]

Thanks for the 🥞!

[binghamtj]

Can I unstack them so that I can merge things? Right now I have a PR to Branch A and cannot merge it because the PR from Branch A to Develop is blocking it, seems kind of dumb.

[gracewhitney]

It's the button in the top-right corner of this menu

[diegorubert]

Terrible design choice, the unstack icon is so hard to find...

[rbell-mfj]

Irritating that merging is all-or-nothing within a stack (for any PR above the bottom one). Why can't I just merge at least the top PR into the one below it to simplify the stack?

[ckhall]

@rbell-mfj gh stack modify then fold the one PR into the other PR and apply.

[gilescope]

unstack should be a green button with text.

[ImErvin]

A share button that copies the links to each PR in the stack so I can share with my colleagues when asking them to review

[d-feliz]

Or sharing the entire stack as a single thing. Sharing link to a page that displays the entire stack would be great also.

[isaksky]

It would be great if you made it so these new stack commands worked via github PATs - otherwise it will be a little dangerous with agents (you have to give them full access).

[dxqb]

this feature looks really promising, but I think it only becomes useful when a contributor who doesn't have access to the repo can stack PR submissions. unless I'm missing something, all branches must be in the same repo currently. They aren't when you submit a PR to another repo, and you might want to stack onto your first PR

[stevehipwell]

Even for non-public repos, having to grant write access to all contributors is an anti-pattern due to the lack of granularity in the GitHub RBAC model.

[torarnv]

This is a key missing piece of this feature in my mind. The typical workflow of finding a project you want to contribute to on GitHub is that you make a personal fork, and push your changes there, creating a corresponding PR in the upstream repo.

And then you find another thing to fix, that touches the same code, but isn't a related feature. So your second topic branch and PR pulls in the commits from the first topic branch and PR. Super annoying for both contributors and reviewers to deal with.

Crossing fingers cross repo stacked PRs will make it in before release! 😊

[stevehipwell]

As an OSS maintainer I want to be able to stack up a number of community PRs so that we can merge them as one rather than having to rebase all PRs each time one is merged. Obviously the lack of signing support is also going to break this workflow in the same way it breaks the maintainer rebase button and rebase merge strategy.

[MichaelChirico]

+100 to this. I can't believe this wasn't solved before initial release. This should be P0.

[jglick]

github/gh-stack#18 (comment)

[ghicks-novaprime]

I have a use case for this that would be greatly improved with a pretty minor change.

Occasionally, I need to make a change that should be deployed in multiple separate steps. For example, removing an S3 bucket from a Terraform deployment - first I need to merge a change to enable force-destroy and apply that (so it can be removed without emptying its contents first), then I need to merge a second change to actually remove it.

Stacked PRs look like a great way to create both PRs ahead of time and mark them as related for reviewers, but I don't see any way for the stack creator to force the individual PRs to be merged separately. In the case I described above, someone merging both of them at once defeats the purpose and causes a failed apply.

If I could disable merging multiple PRs at once for a specific stack, it would be much more useful and safer for this use case.

[Ritik574-coder]

That makes sense, especially for infrastructure changes where deployment order matters. A per-stack option to enforce sequential merging could make stacked PRs much safer for workflows like Terraform.

It might be even better if each PR in the stack could be marked as dependent on the previous one, so the next PR becomes mergeable only after the previous PR has been merged successfully. That would preserve the intended deployment order rather than relying on reviewers to remember it.

[FatTailSec]

I lowkey dislike the github stacks feature they added
[2:19 PM]no ability to merge intermediate stages its all or one into the default branch

[bienjamon]

yea, my expectation was that I would be able to consolidate prs in the stack incrementally. That workflow exists with feature branches, just in a more cumbersome way, and I was hoping stacks would help make that process easier

[bienjamon]

It even seems worse than that, because if I can't incrementally merge, then I have to respond to PR feedback in branching histories, so instead of starting on the leafs and reviewing and merging towards the trunk, I have to start at the pr closest to the trunk, and work my way out, resolving and re-resolving any merge conflicts along the way

[Ritik574-coder]

Yeah, I think that's one of the biggest limitations right now. Being able to merge an intermediate PR independently would make stacks much more flexible, especially when each stage needs to be deployed or validated before the next one is merged.

[kyle-query]

It's a complete mess when using squash merges too. I thought it would auto-rebase the upstack PRs but that fails with merge conflicts due to the squash merge. I guess it only makes sense if (a) you're using merge/rebase commits and/or (b) you're going to merge the entire stack at once(?), though I'm not even sure that would work.

[nalvelo]

EDIT: Seems there is a phased rollout, as we now have support!

This feature is not currently working for any repo in our organization that has a Merge Queue. Is there any guidance of how to enable this? I verified this to see 404 vs. 200 statuses for the stack feature against all of our repos.

[Ritik574-coder]

This sounds like an important compatibility gap, especially for organizations that rely on Merge Queue for protected branches. It would be helpful to know whether stacked PRs are currently expected to work with Merge Queue, or if repositories using Merge Queue are intentionally excluded during the rollout.

If it is a rollout limitation, some documentation or an explicit UI message would also be much clearer than returning a 404.

[joerobot]

Also looking for more clarity here

[KyleBastien]

+1 this was super confusing to me.

[seanmsmith23]

Would love an update here.

[JarredAllen]

My repo with a merge queue just got stacked PRs support today, not sure if everyone has it or if they're doing a staggered rollout.

[JeremasPosta]

Nothing indicates that there is a conflict:

Then, upon rebasing, a conflict exists on the 'current' PR

And now I don't have the web editor option to solve the supposed conflict.

[MarionToutant]

yep same for me, and in the end I pulled manually master onto my lower branch, and there was actually no conflict at all (i don't know where it found it in the first place)

[jcrodriguezu]

Same here, tried different times, not working. I have to it manually

[SaiShankar93]

came here to post the same issue , the new stacking PR feature is not indicating the merge conflicts

[kyle-query]

I don't think this "stacked PR" feature works at all with squash merging into main. We already stack PRs (P1 -> main, P2 -> P1, P3 -> P2, etc) and I thought the merge conflict issue with squash merging + stacked PRs was solved by this feature, but it really doesn't seem to provide any discernable benefit. I can't even squish my PR branches down to one commit and use merge/rebase commits without having the same problem.

[danilofuchs]

Would be nice to be able to mark a whole stack as "ready for review" at once

[imanmahjoubi]

Thank you for the feedback! Sharing this with the team

[chrismikehogan]

adding onto this it would be nice to be able to assign the same reviewer to a given stack. often you need the context from previous layers to review a given layer.

[BethelH]

All commits before the stack are suddenly unverified even though no changes were made to my local signing ability, any commits pushed up after stacking are verified as usual

[jsync-swirlds]

We experienced this same issue, and it makes stacked PRs unusable in our org.

As soon as Github tries to rebase the second PR in the stack against the post-merge of the first, the commit becomes unverified, and the stack merge stops.

Also, some CI checks seem to either block the stack (because they are required, and are not run or cannot be run) or cause a timeout (because the CI checks take a long time).

I would expect the following:

1. The commits to be merged are frozen when the stack merge begins, and cannot change during the stack merge.
2. When merging a stack, CI must pass before starting the merge, so it should not be re-run during the merge.
3. Approvals are considered prior to the stack merge, and are not dismissed during the stack merge.

[pavel-mikula-sonarsource]

We're facing the same issue with the author and squash-merge.
Even the 1st PR in queue was reassigned to the reviewer as the author.

While the feature is generally amazing, this is a blocker.

[imanmahjoubi]

The team is currently working on a fix. Thanks for sharing 🙏🏼

[Maxr1998]

@imanmahjoubi can we expect a timeline on when this is fixed? This has bitten our team multiple times already, and I'm honestly surprised this bug even went into production considering the main responsibility of GitHub is managing commits correctly…

[thomass-dev]

The "author/email address" bug is still there as of today.

[mustikka10]

Copilot

[mustikka10]

Copilot

[clementzach]

In case you're looking for "dumb things people can do to mess up their stacks", here's one thing I did:

My setup is that I have two separate directories where my git repos are. When an agent is working in directory 1, I'll make changes in directory 2 in another branch. (I know now that I should be using work trees for this but oh well)

Then, I did these steps:

1. Set up a stack of a few PRs in directory 1 with branch names stack-1, stack-2, stack-3
2. Set up a stack in GitHub
3. Have an agent working in directory 1 on one o the stacks
4. Go to directory 2 (which doesn't have any of the stacks) and do git fetch origin stack-1 and git checkout stack-1
5. Then do gh stack sync

After I ran this, a bunch of PRs in the stack had a ghost "merge" happen--it said they had merged into the main branch in GitHub but the commits weren't on main.

This was on my company account so I can't link here, I'll see if I can replicate it on this account and update later to link to this

[chipxsd]

Maintaining a stack of PRs is impossible on our fast moving main — and rebasing the stack wastes a lot of CI time.

What we'd rather have, is an ability to treat it more like a feature branch, where individual branches are merged into the feature branch, nicely visualized with the PR UI as a graph, rather than a stack.

[mustikka10]

Maintaining a stack of PRs is impossible on our fast moving main — and rebasing the stack wastes a lot of CI time.

What we'd rather have, is an ability to treat it more like a feature branch, where individual branches are merged into the feature branch, nicely visualized with the PR UI as a graph, rather than a stack.

[esatterwhite]

what not create a stack that targets the feature branch then merge the stack into that. merging the result in to main.
I don't think targeting main is a requirement in a stack

[crhaglun]

This is a practical problem that makes stacked PRs exceptionally challenging to adopt for my team.

Stacked PRs would be most useful for complex changes requiring cross-function signoffs. But having to rebase every time the main branch is updated means reviews get stuck forever in review.

Somehow treating the first layer of a stacked PR as a normal feature branch, only blocking completion on merge conflicts, would go a long way towards making this feature useful.

[augustdolan]

This may not be "fixable" Due to gh stack rebase rebasing main (which does make sense), but every time I want to rebase a change I made in my stack to its children, all PRs in the stack, including parents, rebase. Submitting then pushes more or less empty changes for X number of PRs, which can cost notable CI dollars to be running actions for nothing (not to mention can cause me to need to wait for CI to clear to get a clear picture of the state of those parent PRs). I would love to be able to run gh stack rebase and have it only propagate changes from my current stack layer to its children.

[Cjstoney]

Summary

Clicking Enqueue stack on a stack where two or more PRs merge in the same
merge-queue batch causes the next PR up the stack to be silently closed instead
of merged. The auto-retarget resolves only one level up — onto the immediate
parent's base — and when that grandparent branch is part of the same batch, it
is deleted in the same instant. The child PR is then closed by the
branch-deletion handler and removed from the merge queue.

Steps to reproduce

Environment

• gh stack version 0.1.0
• Private repo
• Repo has delete_branch_on_merge: true
• Repo uses GitHub merge queue (merge_group triggers)
• 5-PR stack on main

1. Create a stack: main ← A ← B ← C ← D ← E, where B's base is A's head branch
   and C's base is B's head branch.
2. Ensure "Automatically delete head branches" is enabled and a merge queue is
   configured.
3. Click Enqueue stack.
4. Let the queue merge A and B in a single batch.

Expected

C is retargeted to the first surviving ancestor (here main), stays open, and
remains in the merge queue to be merged in turn.

Actual

C is retargeted onto A's head branch, which the same batch deletes. C is closed
and evicted from the queue. The stack stalls with C, D, E orphaned.

Evidence

PRs #19465 and #19467 merged in the same second, one batch:

19465  merged 2026-08-27T16:43:39Z  base=main        head=branch-a
19467  merged 2026-08-27T16:43:39Z  base=branch-a    head=branch-b

Timeline for #19477 (the next PR up), from
/repos/{owner}/{repo}/issues/19477/timeline:

2026-08-27T16:22:54Z  added_to_merge_queue
2026-08-27T16:43:41Z  automatic_base_change_succeeded
2026-08-27T16:43:41Z  base_ref_deleted
2026-08-27T16:43:41Z  closed
2026-08-27T16:43:41Z  removed_from_merge_queue

automatic_base_change_succeeded fired and moved #19477's base to branch-a —
#19467's base — which #19465 had just merged and which auto-delete removed in
the same second. #19477's base was confirmed as that branch immediately
afterward.

Two details rule out "working as intended": added_to_merge_queue shows the
enqueue fully accepted #19477 rather than deliberately excluding it, and
automatic_base_change_succeeded shows the retarget logic ran and reported
success — it just picked a doomed target.

Impact

The PR is closed, not just blocked, so review history and approvals are
stranded. Running gh stack submit afterward does not repair it — it opens a
duplicate PR for the same head branch and reports
Merged PRs have left the stack on GitHub, so it wasn't updated.

Aggravating factors during recovery

• gh pr reopen fails with a bare GraphQL: Could not open the pull request.
  The REST equivalent gives the real reason
  (the branch was force-pushed or recreated) — the GraphQL path should surface
  this.
• A PR cannot be reopened while its base ref is missing, so recovery requires
  resurrecting the deleted branch by SHA.
• gh pr edit --base is rejected with
  Cannot change the base branch because the pull request is part of a stack.
• gh stack unstack cannot detach the stack at all:
  Pull requests #19465, #19467 cannot be removed from this stack. Once PRs
  merge they are pinned, and unstacking is all-or-nothing, so the escape hatch
  is unavailable exactly when it is needed.

Suggested fix

Resolve the auto-retarget to the nearest ancestor that will still exist after
the batch completes (or to the stack trunk), and/or suppress the branch-deletion
close path for PRs that are members of an active stack.

Workaround

Enqueue the bottom PR alone, wait for the merge and retarget to settle, then
enqueue the next.

[vsiao]

see also github/gh-stack#443 and github/gh-stack#444

[andmehta]

I think it'd be pretty normal to want to drop a PR from a stack. And that seems to be supported EXCEPT on the last PR on the stack? I can understand not wanting to try and support a strange rebase directly, but even on the case where I have merged the bottom N, and the final piece of the stack is unmerged?

If I do a gh stack unstack I'll lose the whole stack history, which is quite nice to see the flow, I just added 1 too many PRs to this stack so would like to clean it up?

[andrewring]

It appears that the "Merge when ready" option with merge queues is currently missing for stacks. Is that a bug, or is it just a roadmap item not yet implemented?

[seob717]

+1 for cross-fork stack support.

My use case: I maintain a downstream fork and regularly send changes to the upstream repository. Since all branches in a stack must live in the same repository, the entire feature is unavailable for the standard fork-based contribution flow — which is how most open-source contributions (and downstream fork setups) work.

On the rebase side: I understand rebasing necessarily rewrites commit SHAs, and the automatic restack on merge is genuinely nice. Given that trade-off is inherent to the design, fork support feels like the bigger gap — without it, external contributors cannot use stacks at all, while same-repo teams already get the full workflow.

Is cross-fork support planned for GA?

[lstellway]

Good Problem

Stacks touch on a real issue:
I have struggled with how to break down larger bodies of work into incremental changes that still require reviews on a large team.

Merging from the "bottom" of the stack is the safest / most incremental way to introduce change, but places a big burden on the developer to sync everything up the stack once merged. You need to be pretty familiar with git:

My approach before stacks has been to create a new branch from main, cherry-pick the relevant range of commits, get name of original branch, delete it, re-create it with new "rebased" branch, and force-push to the open PR.. and then do that for every other PR all the way up the "stack"

The Implementation

I solely use the gh CLI for creating pull requests, and that job has been delegated more and more to LLM's.

The (AI) skills used to create a stack seem to work well, but manually creating a stack (gh stack init, gh stack add, gh stack submit) feels clunky and unintuitive (my opinion).

The underlying resource we are working with here is still a "Pull Request".
I do not agree with abstracting a whole new (root-level) concept of "Stacks".

I think this concept should be seamlessly integrated into the existing Pull Request experience, rather than exposing this as a new/separate feature to the end user.

The web UI feels pretty good, but the CLI experience is funky — and I imagine it's related to the way it was built, and that complexity is being exposed here (is a "stack" a new entity type?).

Closing

GitHub invented the "Pull Request".
This is a much-needed enhancement (addressing a real need) for us all to adapt to the new landscape.

A new, distinct name is great for giving everyone a label to talk about a new concept, but I think the concept can be more seamlessly integrated.

We already have:

gh pr create --base some-feature-branch

I think a better experience would be as simple as an additional flag here:
(though, I might call it --sync or something similar)

gh pr create --stack

Imagine:

# Create a PR "synced" to its base
gh pr create --sync

# Open TUI to reorder "synced" PR's
gh pr reorder

# Stop syncing a PR
gh pr unsync 1234

# Merging a PR (existing workflow) rebases everything up the "stack" for anything "synced"
# This would be helpful for parallelized work where multiple features are dependent on a base body of work.
gh pr merge

[satwik-xflowpay]

Currently for stack PR's for each PR , we have to set reviewer , can we allow setting a reviewer for a complete stack at once ? Will be a good addition what i feel.

[jozefizso]

Stack PR stack cannot be merged. GitHub shows it is merging individual PRs, then it resets and merges the first PR indefinitely. No logs anywhere.

This experience is so frustrating.

[Leonardo-Zappani]

Two merge problems from a real 11 PR stack, one of which looks like a straightforward bug.

1. The web merge button hangs forever because it does not call the endpoint that works

Clicking Merge on a stacked PR spins on "Merging…" indefinitely with no error and no state change. The PR was MERGEABLE / CLEAN / APPROVED, all required checks green, no merge queue, no auto-merge, nothing pending.

The reason shows up the moment you leave the UI:

$ gh pr merge 7321 --merge
GraphQL: This pull request is part of a stack and must be merged using the
asynchronous merge REST API (mergePullRequest)

$ gh api -X PUT repos/OWNER/REPO/pulls/7321/merge -f merge_method=merge
403 Merging stacked PRs via this endpoint is not supported.
Use the asynchronous merge endpoint instead.

Only PUT /repos/subbase-io/subbase/pulls/{n}/merge-async works, and it merged in about five seconds:

$ gh api -X PUT repos/OWNER/REPO/pulls/7321/merge-async \
    -f merge_method=merge -f sha=<head_sha>
{"status":"pending","details":{"uuid":"...","expected_head_sha":"..."}}

$ gh api repos/OWNER/REPO/pulls/7321/merge-async/<uuid>
{"status":"merged","details":{"message":"Pull request was merged.","sha":"..."}}

So the endpoint exists and is fast. The UI just is not using it, and it fails silently instead of surfacing the same message the API returns immediately. Showing that error would have saved a lot of guessing.

2. Merging the bottom PR invalidates every approval above it

After the bottom PR merged, GitHub retargeted and auto-rebased the rest of the stack. That part worked correctly. But every head SHA above it changed, so every approval went stale at once. Nine PRs, nine approvals gone in one merge, and the same thing would happen again on the next one.

For a stack of any size that makes incremental merging impractical: you collect N approvals, merge one, then re-collect N-1, and so on. We gave up and collapsed the remaining ten PRs into a single branch off the default branch.

If the intended model is "merge the whole stack in one operation" then that is workable, but the per-PR merge button probably should not be offered in that case, and the approval churn is worth documenting. Related: gh has no merge-async wrapper yet, so scripted merges hit the same wall as the UI.

Repo settings in case they matter: squash disabled, merge commits allowed, delete_branch_on_merge on, ruleset with required status checks only, no dismiss-stale rule, no CODEOWNERS.

[dctucker]

This is a useful feature that I'm trying to integrate into my workflow, but I've run into confusion a couple of times now so I figure it's time to offer feedback.

There's a button that says "Rebase stack" that appears on pull requests. Great. I understand what this does. I click it, and all of my branches (on the remote) get rebased. Now that I've done that, my local is out of sync.

I've tried several different ways to get local back in sync with the remote, and the least destructive way seems to be the most tedious because there isn't a single gh stack ... command I can run to do this, and I end up switching to each branch and doing a git pull --rebase. If I do gh stack sync, it does a push that includes a ton of commits that I didn't intend to, possibly because my local main had drifted from remote main.

• Am I "holding it wrong"; issuing the wrong commands in the wrong sequence?
• Could we add a sub-command that automates the process of pulling down changes for each branch in the stack?
• Please clarify what gh stack sync is supposed to do. "Sync the local current stack with the remote" is too ambiguous; It's either a pull or a push.

[linguofeng]

Title: Atomic stack merge is blocked by the base branch's "Require a pull request before merging" rule — the finale is a direct_merge

TL;DR: On a branch protected by a repository ruleset whose pull_request rule requires 1 approving review, an atomic stack merge fails with At least 1 approving review is required by reviewers with write access even though every PR in the stack is APPROVED/CLEAN and the rule-suite records show every layer's pull_request rule passing. The web UI reveals the failure is not in any layer but in a final step (Final merge failed: ...), and the merge-async payload reports "merge_action": "direct_merge". A plain (non-stack) PR into the same branch with the same single approval merges fine. Net effect: stacked merges appear unusable against a trunk that requires a PR.

Environment

• gh stack v0.1.0, gh 2.93.0
• Private repos (reproduced independently in two of them: a 12-PR stack and a 10-PR stack)
• Base branch: a long-lived integration trunk, protected by a repository-level ruleset:
  • pull_request: required_approving_review_count: 1, dismiss_stale_reviews_on_push: true, require_code_owner_review: true (no CODEOWNERS file exists in the repo, so this is vacuous — per-PR reviewDecision is APPROVED), require_extra_approval_for_unattributed_changes: true, require_last_push_approval: **false**, allowed_merge_methods: [merge, squash, rebase]
  • plus deletion and non_fast_forward
  • no required status checks, no merge queue, no classic branch protection on this branch
• Merge method used: squash

Reproduction

1. Build a stack of N PRs (N = 12 and N = 10) rooted on the protected branch; link it (gh stack link).
2. Have a reviewer with write access (not the PR author) approve every layer, after that layer's last push.
3. Verify per-PR state: all layers reviewDecision=APPROVED, mergeStateStatus=CLEAN, chain strictly linear (each layer's parent head is an ancestor of the child).
4. gh stack merge <stack> --yes --merge-method squash

Expected

The stack merges, or the failure names the layer/requirement that is not satisfied.

Actual

Merging #1, #2, ..., #12 into <trunk> via squash...
✗ merge failed: Repository rule violations found

At least 1 approving review is required by reviewers with write access.

Stack merges are atomic, so nothing was merged.

The atomic rollback itself works correctly — the base branch is untouched and no PR is modified (verified: bases and approvals unchanged after each attempt). 👍

Evidence that the failing step is not any of the layers

1. The web UI's rule-evaluation detail names a separate final step:

Rules passed, but PR stack failed
1 ruleset passed
<trunk>-ruleset — Require a pull request before merging (#<top PR>)
  <reviewer> Approved
  Block force pushes
  Restrict deletions
Stack details — Stack position: 12 — Pull requests in this stack: ...
Final merge failed: At least 1 approving review is required by reviewers with write access.

So the ruleset passed for the stack's PRs, and something after that failed with the approval message.

2. The rule-suite API agrees. GET /repos/{o}/{r}/rulesets/rule-suites records one suite per layer for the attempt; each has rule_evaluations[].result = "pass" for pull_request / non_fast_forward / deletion, while the suite's own result is stack_merge_failed. There is no suite whose pull_request evaluation fails.

3. The merge-async payload says the finale is a direct merge:

{"status":"pending","details":{"message":"Merge request is in progress.",
 "uuid":"<uuid>","merge_method":"squash","merge_action":"direct_merge",
 "expected_head_sha":"<top head sha>"}}

… and terminally:

{"status":"failed","details":{"message":"Repository rule violations found\n\nAt least 1 approving review is required by reviewers with write access.\n\n"}}

Control experiment (this is the part that isolates it)

In a third repo of the same org whose pull_request rule parameters are identical (required_approving_review_count=1, require_code_owner_review=true, require_extra_approval_for_unattributed_changes=true, dismiss_stale_reviews_on_push=true; I compared these four, not the whole ruleset object), a plain, non-stacked PR into the same trunk, approved by the same reviewer, with exactly one approval, merged successfully. So the ruleset is satisfiable by an ordinary PR merge; only the stack merge's final step is not.

Things ruled out (each verified, none is the cause)

Hypothesis	Result
Stale approvals	Checked approval submittedAt ≥ head committedDate for every layer. One layer genuinely was stale-but-not-dismissed (see "Secondary observation"); after re-approval all layers were fresh and the merge failed identically.
Commits not attributable to a GitHub account (require_extra_approval_for_unattributed_changes)	Every commit in every layer resolves to a GitHub user (author/committer non-null).
require_code_owner_review	No CODEOWNERS in the repo. (An org-level .github/CODEOWNERS exists but is not in effect: GitHub requested no reviews from those owners and reviewDecision is APPROVED.)
Reviewer lacks write access	Reviewer's permission is write (maintain role).
Classic branch protection	GET /branches/{trunk}/protection → 404.
Organization-level ruleset	GET /repos/{o}/{r}/rules/branches/{trunk} returns only repository-sourced rules.
Merge queue	None on this branch.

Hypothesis

The atomic stack merge evaluates each layer as a pull-request merge (all pass), then performs a single ref update on the base branch (merge_action: direct_merge) to land the result. That final ref update is evaluated against the branch's pull_request rule — which by definition rejects updates that do not come through a pull request — and is reported with the generic "needs an approving review" text. gh stack merge --help states that "Bypassing merge requirements is not supported for stacks", so there is no way to let that step through.

I can't see the server side, so this is an inference from the three observations above; the observations themselves are reproducible.

Impact

Any repository whose trunk requires a pull request — i.e. the normal setup that stacked PRs are meant for — cannot use atomic stack merge against that trunk. Two independent repos, four attempts, identical failure.

The error text also actively misleads: it names a missing approval when every PR has one from a write-access reviewer. It cost us a full round of re-requested reviews from a human reviewer before we found the "Final merge failed" line, which is only visible in the web UI's rule-evaluation detail page — the CLI does not surface it.

Workaround (works today)

Land the stack on an intermediate branch that has no rules, then merge that branch into the trunk with an ordinary PR:

1. git push origin origin/<trunk>:refs/heads/integration/x.y.z — verify GET /repos/{o}/{r}/rules/branches/integration%2Fx.y.z returns [], and that the branch name does not match any CI trigger pattern.
2. gh stack unstack <stack> — required, because a PR in a stack refuses base changes: Cannot change the base branch because the pull request is part of a stack. (422)
3. PATCH /repos/{o}/{r}/pulls/<bottom PR> with base=integration/x.y.z
4. gh stack link --base integration/x.y.z <all PRs, bottom to top> (this creates a new stack number)
5. gh stack merge <new stack> --yes --merge-method squash → succeeds; every layer lands as its own commit and every PR is marked MERGED
6. Open one ordinary PR integration/x.y.z → <trunk>, one approval, merge commit (squashing here would collapse the per-layer commits and defeat the purpose)

Cost: one extra hop, one extra approval, and the bottom PR's base change risks dismissing its approval.

Suggestions

1. Make the finale not require a separate PR-based approval — it is the result of merging pull requests that each satisfied the rule.
2. If that is intended behaviour, say so in the error: name the step ("final merge") and the rule, instead of a generic missing-approval message. Surfacing the web UI's Final merge failed: line in the CLI output would have saved us hours.
3. Consider documenting the intermediate-branch workaround, or supporting a --via <branch> style option that does it.

Relationship to existing reports

Different from the ones I found, though possibly the same subsystem:

• Discussion #465 and #404 — both involve require_last_push_approval: true (and CODEOWNERS) and fail with "Waiting on reapproval from someone other than the last pusher / review is stale because the merge base changed". Ours has require_last_push_approval: false, no CODEOWNERS in effect, and a different error string, and our rule-suites show every layer passing.
• Issue #323 — same "everything looks mergeable" feeling, but that one rolls back silently with "auto-merge was automatically disabled — Pull Request is not mergeable" and has require_last_push_approval: true plus required status checks. We have neither.

If maintainers think these are one root cause, happy to have this folded in — the merge_action: direct_merge + Final merge failed pairing may be the common mechanism.

Secondary observations (separate from the above; can file separately if useful)

1. dismiss_stale_reviews_on_push did not fire for exactly one layer after gh stack push of a rebased stack — in both repos it was the layer immediately above the one whose head changed. Those PRs kept reviewDecision=APPROVED with an approval ~4 hours older than their head commit. reviewDecision is therefore not a safe acceptance signal after a stack rebase; comparing approval time to head-commit time is.
2. gh stack rebase --upstack produced conflicts that a per-layer git rebase --onto did not. In one repo it stopped with conflicts in files whose changes belong to that layer's own internal commit sequence (one of them DU — deleted-by-us — because the file is created by a later commit in the same layer). Replaying only each layer's own commits (git rebase --onto <new parent> <old parent> <child>) applied cleanly for all 9 layers. In the other repo --upstack was clean, so this is not deterministic.