update to support merge queue

Author: skarim

.github/copilot-instructions.md

@@ -17,7 +17,7 @@ No Makefile, no code generation, no external linter config. Standard Go toolchai
 
 - `cmd/`: One Cobra command per file. Each exports `<Name>Cmd(cfg *config.Config)` with logic in `run<Name>()`.
 - `internal/git/`: `Ops` interface (52 methods) wrapping git CLI. `MockOps` for tests. Package-level functions delegate to swappable `ops` variable.
-- `internal/github/`: `ClientOps` interface (18 methods) for GitHub API. `MockClient` for tests. Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`); merges use the async merge API (`/repos/{owner}/{repo}/pulls/{n}/merge-async`), with `BaseBranchPolicy` (GraphQL) gating merge-queue branches.
+- `internal/github/`: `ClientOps` interface (17 methods) for GitHub API. `MockClient` for tests. Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`); merges use the async merge API (`/repos/{owner}/{repo}/pulls/{n}/merge-async`), which routes to a direct merge or the base branch's merge queue automatically.
 - `internal/config/`: `Config` struct passed to all commands. Holds I/O, colors, and test hooks (`SelectFn`, `ConfirmFn`, `InputFn`, `GitHubClientOverride`).
 - `internal/stack/`: Stack file (`.git/gh-stack`, JSON) management with file locking.
 - `internal/tui/`: bubbletea views (`stackview`, `modifyview`).

AGENTS.md

@@ -35,7 +35,7 @@ internal/
     gitops.go                # Ops interface (52 methods)
     mock_ops.go              # MockOps. Each method has a corresponding *Fn field.
   github/                    # github.ClientOps interface + real Client
-    client_interface.go      # ClientOps interface (18 methods)
+    client_interface.go      # ClientOps interface (17 methods)
     mock_client.go           # MockClient. Uses function-pointer fields for testing.
   stack/                     # stack file (.git/gh-stack) management, JSON schema, locking
     schema.json              # JSON Schema for the stack file format
@@ -109,7 +109,7 @@ if errors.As(err, &exitErr) { ... }
 ### Key interfaces
 
 - **`git.Ops`** (`internal/git/gitops.go`): 52 methods wrapping git CLI calls. The production implementation uses `cli/go-gh`'s `client.Command()` via `run()` and `runSilent()` helpers. Package-level functions (e.g., `git.CurrentBranch()`) delegate to a swappable package-level `ops` variable.
-- **`github.ClientOps`** (`internal/github/client_interface.go`): 18 methods for GitHub API (PRs, stacks, merges). Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`): `ListStacks`, `FindStackForPR`, `GetStack`, `CreateStack`, `AddToStack` (delta append), `Unstack`. Async stack merges use `RepoMergeConfig` (GraphQL allowed methods + viewer default), `MergeStackAsync`, and `GetAsyncMergeResult` (`/repos/{owner}/{repo}/pulls/{n}/merge-async`); `BaseBranchPolicy` (GraphQL) reports whether the base branch requires a merge queue (unsupported). Injected via `cfg.GitHubClientOverride` in tests.
+- **`github.ClientOps`** (`internal/github/client_interface.go`): 17 methods for GitHub API (PRs, stacks, merges). Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`): `ListStacks`, `FindStackForPR`, `GetStack`, `CreateStack`, `AddToStack` (delta append), `Unstack`. Async stack merges use `RepoMergeConfig` (GraphQL: allowed merge methods + viewer's default), `MergeStackAsync`, and `GetAsyncMergeResult` (`/repos/{owner}/{repo}/pulls/{n}/merge-async`). Injected via `cfg.GitHubClientOverride` in tests.
 - **`config.Config`** (`internal/config/config.go`): Central configuration passed to all commands. Holds I/O streams, color functions, and test hook fields (`SelectFn`, `ConfirmFn`, `InputFn`, `RepoOverride`).
 
 ### Stack file

README.md

@@ -453,9 +453,9 @@ With no argument, the current active local stack is used. Pass a stack number to
 
 In an interactive terminal, a short wizard walks you through three steps — choose which PRs to merge, pick the merge method, and confirm. In a non-interactive terminal, or with `--yes`, the whole stack (or everything up to the given PR) is merged without prompting, using your last-used merge method unless one is specified.
 
-Only basic pull request state is checked before merging (open and not a draft); GitHub evaluates branch protection and repository rules when the merge runs, so any such failure is reported back to you. **Admin bypass is not supported** for stacked PR merges at this time.
+Only basic pull request state is checked before merging (open and not a draft); GitHub evaluates branch protection and repository rules when the merge runs, so any such failure is reported back to you. **Bypassing merge requirements is not supported** for stacked PR merges.
 
-Note that this command does not work with merge queues. If the stack's base branch uses a merge queue, use `gh pr merge` instead.
+If the base branch uses a merge queue, the stack is added to the queue and merges once the queue processes it; otherwise it's merged directly.
 
 | Flag | Description |
 |------|-------------|

cmd/merge.go

@@ -63,10 +63,11 @@ prompting, using your last-used merge method unless one is specified.
 
 Only basic pull request state is checked before merging (open and not a draft);
 GitHub evaluates branch protection and repository rules when the merge runs, so
-any such failure is reported back to you.
+any such failure is reported back to you. Bypassing merge requirements with admin
+privileges is not supported for stacks.
 
-If the base branch uses a merge queue, this command isn't supported (it merges
-directly, not through the queue); use "gh pr merge" or the web UI instead.`,
+If the base branch uses a merge queue, the stack is added to the queue and merges
+once the queue processes it; otherwise it is merged directly.`,
 		Example: `  # Merge the current stack (interactive picker)
   $ gh stack merge
 
@@ -143,18 +144,6 @@ func runMerge(cfg *config.Config, opts *mergeOptions, args []string) error {
 
 	base := remoteStack.Base.Ref
 
-	// Merge-queue and admin-bypass policy for the stack's base branch. The async
-	// stack merge cannot use a merge queue, so bail out early (before any
-	// prompting) when the base requires one.
-	policy, err := client.BaseBranchPolicy(base)
-	if err != nil {
-		cfg.Errorf("failed to check base branch merge settings: %s", err)
-		return ErrAPIFailure
-	}
-	if policy.RequiresMergeQueue {
-		return explainMergeQueueUnsupported(cfg, base)
-	}
-
 	if cfg.IsInteractive() && !opts.yes {
 		return runMergeInteractive(cfg, client, remoteStack.Number, base, candidates, allowed, mergeCfg.DefaultMethod, method, preselectIndex, opts)
 	}
@@ -328,6 +317,9 @@ func runMergeInteractive(cfg *config.Config, client github.ClientOps, stackNumbe
 	case out.Merged:
 		mergedSuccess(cfg, prNumberList(out.MergedPRs), base, out.SHA)
 		return nil
+	case out.Enqueued:
+		enqueuedSuccess(cfg, prNumberList(out.MergedPRs), base)
+		return nil
 	case out.Failed:
 		cfg.Errorf("merge failed: %s", out.Message)
 		cfg.Printf("Stack merges are atomic, so nothing was merged.")
@@ -362,6 +354,10 @@ func runMergeHeadless(cfg *config.Config, client github.ClientOps, base string,
 		mergedSuccess(cfg, list, base, res.Details.SHA)
 		return nil
 	}
+	if res.IsEnqueued() {
+		enqueuedSuccess(cfg, list, base)
+		return nil
+	}
 	if res.IsFailed() {
 		cfg.Errorf("merge failed: %s", res.Details.Message)
 		cfg.Printf("Stack merges are atomic, so nothing was merged.")
@@ -394,6 +390,10 @@ func runMergeHeadless(cfg *config.Config, client github.ClientOps, base string,
 			mergedSuccess(cfg, list, base, status.Details.SHA)
 			return nil
 		}
+		if status.IsEnqueued() {
+			enqueuedSuccess(cfg, list, base)
+			return nil
+		}
 		if status.IsFailed() {
 			cfg.Errorf("merge failed: %s", status.Details.Message)
 			cfg.Printf("Stack merges are atomic, so nothing was merged.")
@@ -430,6 +430,8 @@ func toMergeStatus(res *github.AsyncMergeResult) mergeview.MergeStatus {
 	switch {
 	case res.IsMerged():
 		status = mergeview.StatusMerged
+	case res.IsEnqueued():
+		status = mergeview.StatusEnqueued
 	case res.IsFailed():
 		status = mergeview.StatusFailed
 	}
@@ -504,15 +506,6 @@ func warnAsyncMergeUnavailable(cfg *config.Config) {
 	cfg.Warningf("Async stack merge is not available for this repository")
 }
 
-// explainMergeQueueUnsupported reports that the stack's base branch merges
-// through a merge queue, which the async stack merge cannot use, and points the
-// user to the merge queue (via `gh pr merge` or the web UI) instead.
-func explainMergeQueueUnsupported(cfg *config.Config, base string) error {
-	cfg.Errorf("the base branch %q requires a merge queue, which \"gh stack merge\" does not support", base)
-	cfg.Printf("Merge this stack using `%q` or from the GitHub web UI instead.", "gh pr merge")
-	return ErrSilent
-}
-
 // mergeFailureExit maps a merge failure message to an exit code: rebase/merge
 // conflicts get ErrConflict, everything else ErrAPIFailure.
 func mergeFailureExit(message string) error {
@@ -635,6 +628,13 @@ func mergedSuccess(cfg *config.Config, list, base, sha string) {
 	cfg.Successf("Merged %s into %s", list, base)
 }
 
+// enqueuedSuccess prints the success line when the base branch uses a merge
+// queue: the stack was added to the queue and will merge once it's processed.
+func enqueuedSuccess(cfg *config.Config, list, base string) {
+	cfg.Successf("Added %s to the merge queue for %s", list, base)
+	cfg.Printf("They will merge once the queue processes them.")
+}
+
 func isNotFound(err error) bool {
 	var httpErr *api.HTTPError
 	return errors.As(err, &httpErr) && httpErr.StatusCode == http.StatusNotFound

cmd/merge_test.go

@@ -347,28 +347,43 @@ func TestRunMerge_AlreadyMergedOnSubmit(t *testing.T) {
 	assert.Contains(t, output, "Merged #1, #2 into main")
 }
 
-func TestRunMerge_MergeQueueRequired(t *testing.T) {
+func TestRunMerge_Enqueued(t *testing.T) {
 	cfg, outR, errR := config.NewTestConfig()
 	cfg.GitHubClientOverride = &github.MockClient{
 		GetStackFn: func(n int) (*github.RemoteStack, error) {
 			return remoteStack(7, "main", openStackPR(1, "b1"), openStackPR(2, "b2")), nil
 		},
-		BaseBranchPolicyFn: func(base string) (*github.BaseBranchPolicy, error) {
-			assert.Equal(t, "main", base)
-			return &github.BaseBranchPolicy{RequiresMergeQueue: true}, nil
+		MergeStackAsyncFn: func(pr int, method string) (*github.AsyncMergeResult, error) {
+			return &github.AsyncMergeResult{Status: github.AsyncMergeStatusPending, Details: github.AsyncMergeDetails{UUID: "u"}}, nil
+		},
+		GetAsyncMergeResultFn: func(pr int, uuid string) (*github.AsyncMergeResult, error) {
+			return &github.AsyncMergeResult{Status: github.AsyncMergeStatusEnqueued, Details: github.AsyncMergeDetails{Message: "Pull request was added to the merge queue."}}, nil
+		},
+	}
+
+	err := runMerge(cfg, fastOptions(), []string{"7"})
+	output := collectOutput(cfg, outR, errR)
+
+	require.NoError(t, err)
+	assert.Contains(t, output, "Added #1, #2 to the merge queue for main")
+}
+
+func TestRunMerge_EnqueuedOnSubmit(t *testing.T) {
+	cfg, outR, errR := config.NewTestConfig()
+	cfg.GitHubClientOverride = &github.MockClient{
+		GetStackFn: func(n int) (*github.RemoteStack, error) {
+			return remoteStack(7, "main", openStackPR(1, "b1"), openStackPR(2, "b2")), nil
 		},
 		MergeStackAsyncFn: func(pr int, method string) (*github.AsyncMergeResult, error) {
-			t.Fatal("merge must not be attempted when the base requires a merge queue")
-			return nil, nil
+			return &github.AsyncMergeResult{Status: github.AsyncMergeStatusEnqueued, Details: github.AsyncMergeDetails{Message: "Pull request was added to the merge queue."}}, nil
 		},
 	}
 
 	err := runMerge(cfg, fastOptions(), []string{"7"})
 	output := collectOutput(cfg, outR, errR)
 
-	assert.ErrorIs(t, err, ErrSilent)
-	assert.Contains(t, output, "merge queue")
-	assert.Contains(t, output, "web UI")
+	require.NoError(t, err)
+	assert.Contains(t, output, "Added #1, #2 to the merge queue for main")
 }
 
 func TestRunMerge_AsyncMergeUnavailable(t *testing.T) {

docs/src/content/docs/guides/workflows.md

@@ -143,7 +143,7 @@ gh stack merge --yes --squash
 
 In an interactive terminal, a short wizard lets you choose how far up the stack to merge, pick the merge method (only the ones your repository allows, defaulting to your last-used method), and confirm — then shows live progress. In a non-interactive terminal, or with `--yes`, the whole stack (or everything up to the given PR) is merged without prompting. After merging, run `gh stack sync` to update your local branches.
 
-The exception is a trunk that uses a merge queue: `gh stack merge` merges directly rather than through the queue, so it isn't supported there. Use `gh pr merge` or the GitHub web UI to merge through the queue instead.
+If the base branch uses a merge queue, `gh stack merge` adds the stack to the queue instead of merging directly — it merges once the queue processes it.
 
 :::note[Admin bypass not supported]
 Stack merges currently do not support admin bypass merging.

docs/src/content/docs/reference/cli.md

@@ -474,9 +474,9 @@ With no argument, the current active local stack is used. Pass a stack number to
 
 In an interactive terminal, a short wizard walks you through three steps — choose which PRs to merge, pick the merge method, and confirm. In a non-interactive terminal, or with `--yes`, the whole stack (or everything up to the given PR) is merged without prompting, using your last-used merge method unless one is specified.
 
-Only basic pull request state is checked before merging (open and not a draft); GitHub evaluates branch protection and repository rules when the merge runs, so any such failure is reported back to you. **Admin bypass is not supported** for stacked PR merges at this time.
+Only basic pull request state is checked before merging (open and not a draft); GitHub evaluates branch protection and repository rules when the merge runs, so any such failure is reported back to you. **Bypassing merge requirements is not supported** for stacked PR merges.
 
-Note that this command does not work with merge queues. If the stack's base branch uses a merge queue, use `gh pr merge` instead.
+If the base branch uses a merge queue, the stack is added to the queue and merges once the queue processes it; otherwise it's merged directly.
 
 | Flag | Description |
 |------|-------------|

internal/github/client_interface.go

@@ -21,7 +21,6 @@ type ClientOps interface {
 	MergeStackAsync(prNumber int, method string) (*AsyncMergeResult, error)
 	GetAsyncMergeResult(prNumber int, uuid string) (*AsyncMergeResult, error)
 	PRTitles(numbers []int) (map[int]string, error)
-	BaseBranchPolicy(baseRef string) (*BaseBranchPolicy, error)
 }
 
 // Compile-time check that Client satisfies ClientOps.