gh stack merge: no merge-when-ready, and gh pr merge --auto is refused for stacked PRs #591

Summary

For pull requests in a stack there is no way from the CLI to say "merge this when the required checks pass". gh pr merge --auto is refused by GitHub for stacked PRs, and gh stack merge has no equivalent: it fails at once if a required check is still running.

Automation that lands stacked PRs (dependency-update bots, review bots, coding agents) therefore has to detect whether a PR is in a stack, choose between two commands, and poll the checks itself before calling gh stack merge.

What I observed

Environment: gh 2.103.0, gh stack 0.2.1, Linux. Repository with a ruleset containing a squash merge queue and one required status check (gate, a job that sleeps 150 seconds on pull_request and merge_group). Stack of two PRs, #1 (base main) and #2 (base #1's branch), both with the check still running.

1. gh pr merge 1 --repo OWNER/REPO --auto --squash (same for 2):

! The merge strategy for main is set by the merge queue
GraphQL: Auto-merge is not supported for stacked pull requests. (enablePullRequestAutoMerge)

Exit status 1.

2. gh stack merge --yes --squash, run while gate was still in progress:

⚠ the base branch "main" uses a merge queue; ignoring the merge method
Adding #1, #2 to the merge queue for main...
✗ merge failed: Pull request Required status check "gate" is in progress.
Stack merges are atomic, so nothing was merged.

Exit status 4. Nothing was enqueued and both PRs stayed open.

3. gh stack merge --auto --yes --squash:

unknown flag: --auto

Exit status 1. The flags listed by gh stack merge --help are --merge, --merge-method, --rebase, --squash and --yes.

4. The same command as in step 2, run after gate had passed on both PRs:

⚠ the base branch "main" uses a merge queue; ignoring the merge method
Adding #1, #2 to the merge queue for main...
✓ Added #1, #2 to the merge queue for main
They will merge once the queue processes them.

Exit status 0. The queue ran the check on the merge group and merged both PRs about four minutes later.

Reproduction

Create a repository with a merge queue and a required check, then:

gh stack init exp-a        # commit a change
gh stack add exp-b         # commit a change
gh stack submit --auto --open --remote origin
gh pr merge 1 --auto --squash         # refused, see 1
gh stack merge --yes --squash         # while the check runs, see 2

Why it matters

A PR outside a stack can be told to merge once ready (gh pr merge --auto), which is what bots and agents rely on. For a stack the caller has to write a wrapper that checks stack membership, picks the command, and waits for the required checks before the merge call, because that call does not wait. Every project automating stacked PRs ends up writing the same wrapper.

Suggestions

Any one of these would remove the need for it:

• gh stack merge --auto: enable merge-when-ready, or enqueue as soon as the required checks pass, for the stack or for everything up to a given PR.
• gh pr merge recognising a stacked PR and either delegating to the stack merge or naming gh stack merge in its error message.
• Native auto-merge for stacked PRs on the GitHub side, merging bottom-up.