merge cmd docs

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 (13 methods) for GitHub API. `MockClient` for tests. Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`).
+- `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/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 (13 methods)
+    client_interface.go      # ClientOps interface (18 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
@@ -57,7 +57,7 @@ skills/                      # AI agent skill definition (SKILL.md)
 | Group | Commands |
 |-------|----------|
 | Stack management | `init`, `add`, `view`, `checkout`, `modify`, `unstack` |
-| Remote operations | `submit`, `sync`, `rebase`, `push`, `link` |
+| Remote operations | `submit`, `sync`, `rebase`, `push`, `link`, `merge` |
 | Navigation | `switch`, `up`, `down`, `top`, `bottom`, `trunk` |
 | Utilities | `alias`, `feedback` |
 
@@ -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`): 13 methods for GitHub API (PRs, stacks). Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`): `ListStacks`, `FindStackForPR`, `GetStack`, `CreateStack`, `AddToStack` (delta append), `Unstack`. Injected via `cfg.GitHubClientOverride` in tests.
+- **`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.
 - **`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

@@ -439,6 +439,46 @@ gh stack link 42 43 feature-auth feature-ui
 gh stack link --base develop --open feat-a feat-b feat-c
 ```
 
+### `gh stack merge`
+
+Merge one or multiple stacked PRs at once.
+
+```
+gh stack merge [<stack-number> | <pr-number>]
+```
+
+All members of the stack up to and including your chosen pull request are merged into the base branch in a single, all-or-nothing operation: if any PR can't be merged, none are.
+
+With no argument, the current active local stack is used. Pass a stack number to merge a stack you don't have checked out (a purely remote operation), or a pull request number to merge directly up to that PR.
+
+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.
+
+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.
+
+| Flag | Description |
+|------|-------------|
+| `--merge-method <method>` | Merge method to use: `merge`, `squash`, or `rebase` |
+| `--merge` / `--squash` / `--rebase` | Shorthands for the corresponding merge method |
+| `-y, --yes` | Merge without prompting for confirmation |
+
+**Examples:**
+
+```sh
+# Merge the current stack (interactive picker)
+gh stack merge
+
+# Merge a stack you don't have checked out, by stack number
+gh stack merge 7
+
+# Merge everything up to and including PR #42
+gh stack merge 42
+
+# Merge the whole current stack without prompting, squashing
+gh stack merge --yes --squash
+```
+
 ### `gh stack view`
 
 View the current stack.

cmd/merge.go

@@ -63,7 +63,10 @@ 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.
+
+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.`,
 		Example: `  # Merge the current stack (interactive picker)
   $ gh stack merge
 
@@ -501,7 +504,7 @@ func warnAsyncMergeUnavailable(cfg *config.Config) {
 
 // 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 web UI.
+// 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")

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

@@ -33,7 +33,10 @@ gh stack rebase
 # 7. Push the updated branches
 gh stack push
 
-# 8. Sync upstream changes as PRs get merged
+# 8. Land the stack once it's approved (merges bottom to top, atomically)
+gh stack merge
+
+# 9. Sync upstream changes as PRs get merged
 gh stack sync
 ```
 
@@ -120,6 +123,32 @@ gh stack push
 
 The rebase ensures all branches above the changed one pick up the fixes. `gh stack push` uses `--force-with-lease` to safely update the rebased branches.
 
+## Merging Your Stack
+
+When your stack is approved, land it with `gh stack merge`. Regular `gh pr merge` doesn't work with stacked PRs — `gh stack merge` uses GitHub's atomic stack merge, which merges every PR up to and including your chosen one in a single, all-or-nothing operation. If any PR can't be merged, none are.
+
+```sh
+# Merge the current stack (interactive picker for how far up to merge)
+gh stack merge
+
+# Merge everything up to and including a specific PR
+gh stack merge 42
+
+# Merge a stack you don't have checked out, by its stack number
+gh stack merge 7
+
+# Merge without prompting for confirmation, specifying the merge method
+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.
+
+:::note[Admin bypass not supported]
+Stack merges currently do not support admin bypass merging.
+:::
+
 ## Syncing After Merges
 
 When a PR at the bottom of the stack is merged on GitHub, use `gh stack sync` to update your local state:

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

@@ -460,6 +460,48 @@ gh stack link --base develop --open feat-a feat-b feat-c
 
 ---
 
+### `gh stack merge`
+
+Merge one or multiple stacked PRs at once.
+
+```sh
+gh stack merge [<stack-number> | <pr-number>]
+```
+
+All members of the stack up to and including your chosen pull request are merged into the base branch in a single, all-or-nothing operation: if any PR can't be merged, none are.
+
+With no argument, the current active local stack is used. Pass a stack number to merge a stack you don't have checked out (a purely remote operation), or a pull request number to merge directly up to that PR.
+
+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.
+
+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.
+
+| Flag | Description |
+|------|-------------|
+| `--merge-method <method>` | Merge method to use: `merge`, `squash`, or `rebase` |
+| `--merge` / `--squash` / `--rebase` | Shorthands for the corresponding merge method |
+| `-y, --yes` | Merge without prompting for confirmation |
+
+**Examples:**
+
+```sh
+# Merge the current stack (interactive picker)
+gh stack merge
+
+# Merge a stack you don't have checked out, by stack number
+gh stack merge 7
+
+# Merge everything up to and including PR #42
+gh stack merge 42
+
+# Merge the whole current stack without prompting, squashing
+gh stack merge --yes --squash
+```
+
+---
+
 ## Navigation
 
 Move between branches in the current stack without having to remember branch names. The **bottom** of the stack is the branch closest to the trunk, and the **top** is furthest from it. `up` moves away from trunk; `down` moves toward it.

skills/gh-stack/SKILL.md

@@ -7,7 +7,7 @@ description: >
   branch chains, or incremental code review workflows.
 metadata:
   author: github
-  version: "0.0.8"
+  version: "0.0.9"
 ---
 
 # gh-stack
@@ -61,6 +61,7 @@ git config remote.pushDefault origin     # if multiple remotes exist (skips remo
 7. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
 8. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
 9. **Use `gh stack link` for external tool workflows.** When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Provide at least two branches/PRs to create or update a stack, or a stack number followed by the new branches/PRs to append them to the top of an existing stack (e.g. `gh stack link 7 branch-c`).
+10. **Use `gh stack merge --yes` to merge stacked PRs.** `gh pr merge` does not work with stacked PRs. In a non-interactive terminal `gh stack merge` runs without prompting and merges the entire stack (bottom to top) atomically; pass `--yes` to be explicit. Scope the merge by passing a pull request number (`gh stack merge 42 --yes` merges everything up to and including PR #42) or a stack number (`gh stack merge 7 --yes`, which needs no local checkout). Choose the method with `--squash`, `--rebase`, `--merge`, or `--merge-method <method>`; without one, the last-used method is used. The merge is all-or-nothing — if any PR can't be merged, none are, and the failure reason is reported. Only basic pull request state is checked before merging (open and not a draft); admin bypass is not supported for stacked PR merges. This command does not work with merge queues — if the base branch uses a merge queue, the command exits with an error, so use `gh pr merge` instead.
 
 **Never do any of the following — each triggers an interactive prompt or TUI that will hang:**
 - ❌ `gh stack view` or `gh stack view --short` — always use `gh stack view --json`
@@ -164,6 +165,10 @@ Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current
 | Check out by branch (local only) | `gh stack checkout feature-auth` |
 | Tear down the current stack to restructure it | `gh stack unstack` |
 | Tear down a specific stack by number | `gh stack unstack 7` |
+| Merge the whole current stack | `gh stack merge --yes` |
+| Merge a stack by number | `gh stack merge 7 --yes` |
+| Merge up to a specific PR | `gh stack merge 42 --yes` |
+| Merge with a specific method | `gh stack merge --yes --squash` |
 
 ---