shipper_merge

shipper_merge

Run one merge pass over every eligible Ready issue captured at the start, including local changes, and report each outcome and totals. A specified issue runs only that item. Always runs —once (never polls); dry_run previews without changes.

When to use

On macOS, this tool prevents idle system sleep while it performs progress-capable merge work. See Keep the Mac awake during active work. Without issue, it visits every initially eligible Ready issue once in queue order, including local changes, and relays the full CLI report: each outcome and reason, initially excluded skipped records, interrupted unprocessed records, and six totals. Failure or interruption takes precedence over deferral; deferral takes precedence over success. Set dry_run to preview the same captured pass without changing anything; projected outcomes say would merge, route, defer, or fail, while actual inspection errors remain actual. With issue, only that item runs. If a linked PR was already merged outside Shipper, its Ready issue is completed without performing another merge or mutating the PR. Use shipper_get_pr with mode: "checks" first when CI status is uncertain.

Behavior hints

• openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	integer | string	no	-	Shipper issue reference. S# (GitHub #) accepts ordinary surrounding whitespace and requires the current mirror. Bare numbers are Shipper local IDs first; S# is accepted; gh: and # explicitly target a mapped GitHub issue; GitHub issue URLs are accepted. Responses return S# first with GitHub # second when mapped.
dry_run	boolean	no	-	Preview the complete untargeted pass or the specified issue without changes.

Example call

{
  "dry_run": true
}

Example result

[exit 78] shipper merge --once --dry-run
--- stdout ---
One-shot merge pass report:
  S#42 (GitHub #123), PR #17 — would merge
  S#43 (GitHub #124), PR #18 — would defer: checks pending
Initially excluded Ready records (outside eligible pass set):
  S#44 — skipped: blocked at pass start
Totals: merged=1, routed=0, deferred=1, failed=0, skipped=1, unprocessed=0
Dry run: nothing changed.

Error modes

• Timed out merge: [timed out] shipper merge —once
• Failed merge: [exit ] shipper merge —once
• Adopted PR closed or superseded: Adopted PR # for S# (GitHub #) is no longer open or was superseded. Re-adopt the current PR with shipper adopt <pr-number>; Shipper will not guess a replacement automatically.
• Externally merged ready issue: [exit 0] S# completed because its linked PR # was already merged outside Shipper. Shipper did not merge anything.
• Spawn failure: spawn shipper ENOENT

Related tools

• shipper_get_pr