x-merge-pr
Merges a single PR via gh CLI with configurable strategy (merge/squash/rebase), idempotency for already-merged PRs, pre-checks for CI and approvals in synchronous mode, GitHub native auto-merge in --auto mode, and structured error codes. Extracted from x-implement-epic Phase 1.3b to provide a testable, reusable merge primitive callable from x-create-pr --auto-merge and x-implement-epic.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-merge-pr
- description
- Merges a single PR via gh CLI with configurable strategy (merge/squash/rebase), idempotency for already-merged PRs, pre-checks for CI and approvals in synchronous mode, GitHub native auto-merge in --auto mode, and structured error codes. Extracted from x-implement-epic Phase 1.3b to provide a testable, reusable merge primitive callable from x-create-pr --auto-merge and x-implement-epic.
- allowed-tools
- Bash, Read, Write
- argument-hint
- --pr N [--strategy merge|squash|rebase] [--delete-branch true|false] [--auto] [--wait-timeout-min N]
- context-budget
- medium
- user-invocable
- true
- requires-capabilities
- []
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers. Start directly with technical information.
- Progress lines: Prefix with the current phase, e.g.
[Phase 0],[Phase 1],[Phase 2].
Purpose
Merge a single pull request through the GitHub CLI with three orthogonal strategies (merge / squash / rebase), producing a structured result envelope and a deterministic exit code. The skill operates in two mutually exclusive modes:
- Synchronous mode (default) — the skill validates pre-conditions (
mergeable,reviewDecision,statusCheckRollup) before invokinggh pr merge. On success, it returns the merge SHA immediately. - Auto-merge mode (
--auto) — the skill delegates waiting to GitHub's native auto-merge feature (gh pr merge --auto). It returns in under 5 seconds; GitHub will merge the PR asynchronously once CI and approvals are green.
The skill is idempotent: a second invocation on an already-merged PR returns merged=true without error. It replaces the ~80 lines of ad-hoc gh pr merge + polling logic previously embedded in x-implement-epic Phase 1.3b (ADR reference: story-0049-0003, epic-0049 "x-merge-pr extraction").
Triggers
/x-merge-pr --pr 123
/x-merge-pr --pr 123 --strategy squash
/x-merge-pr --pr 123 --strategy rebase --delete-branch false
/x-merge-pr --pr 123 --strategy merge --auto
/x-merge-pr --pr 123 --wait-timeout-min 30
Parameters
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--pr |
Integer (> 0) |
Yes | — | Target PR number. Must exist and be visible to the current gh token. |
--strategy |
Enum (merge | squash | rebase) |
No | merge |
Merge strategy passed to gh pr merge. Maps 1-to-1 to --merge, --squash, --rebase. |
--delete-branch |
Boolean (true | false) |
No | true |
If true, appends --delete-branch to the gh pr merge call. |
--auto |
Flag | No | false |
Enable GitHub native auto-merge (gh pr merge --auto). Skill returns in <5s regardless of CI state. |
--wait-timeout-min |
Integer (1–600) |
No | 60 |
Synchronous-mode timeout in minutes for mergeable=UNKNOWN polling. Ignored when --auto is set. |
Mutual Exclusivity and Validation
--prMUST be a positive integer. Zero, negative, or non-numeric input aborts withPR_NOT_FOUNDbefore anyghcall.--strategyMUST be one ofmerge,squash,rebase. Any other value aborts withINVALID_STRATEGY(exit 1 class).--wait-timeout-minMUST satisfy1 <= N <= 600. Out-of-range values abort withINVALID_TIMEOUT.--autoand--wait-timeout-minare independent; when--autois set,--wait-timeout-minis accepted but ignored (logged as informational warning).
Output Contract
Response Envelope (stdout, single-line JSON)
| Field | Type | Always present | Description |
|---|---|---|---|
merged |
Boolean |
Yes | true when the PR is MERGED at skill exit (synchronous mode). false in --auto mode (merge happens asynchronously). |
mergeSha |
String(40) |
No (synchronous mode only, on success) | SHA of the merge commit reported by gh pr view after merge. Absent on error, absent in --auto mode. |
prState |
Enum (OPEN | MERGED | CLOSED) |
Yes | Final observed PR state. |
waitedSec |
Integer |
Yes | Seconds the skill waited for a state transition (0 when idempotent or --auto). |
autoEnabled |
Boolean |
Yes | true when GitHub auto-merge was successfully enabled by this invocation; false otherwise. |
Example success (synchronous):
{"merged":true,"mergeSha":"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0","prState":"MERGED","waitedSec":12,"autoEnabled":false}
Example success (auto mode):
{"merged":false,"prState":"OPEN","waitedSec":0,"autoEnabled":true}
Example idempotent (already merged):
{"merged":true,"prState":"MERGED","waitedSec":0,"autoEnabled":false}
Exit Codes
| Exit | Error Code | Condition | Message |
|---|---|---|---|
| 0 | — | Success (merge happened, auto enabled, or idempotent no-op) | — |
| 1 | PR_NOT_FOUND |
PR number does not exist or input invalid | "PR #{N} not found" |
| 2 | PR_CLOSED |
PR state is CLOSED without a merge |
"PR #{N} is closed" |
| 3 | NOT_APPROVED |
Synchronous mode: reviewDecision != APPROVED |
"PR #{N} not approved" |
| 4 | CI_FAILING |
Synchronous mode: statusCheckRollup has any FAILURE/ERROR conclusion |
"PR #{N} has failing checks" |
| 5 | MERGE_CONFLICT |
mergeable == CONFLICTING |
"PR #{N} has merge conflicts" |
| 6 | TIMEOUT |
Synchronous mode: mergeable == UNKNOWN persisted past --wait-timeout-min |
"Wait timeout after {N} min" |
Exit codes are stable contract — consumers (e.g., x-implement-epic, x-create-pr --auto-merge) MAY switch on them.
Workflow Overview
Phase 0: Argument parsing + validation — normalize flags, reject invalid input
Phase 1: PR state inspection + idempotency — single gh pr view; exit early if MERGED/CLOSED
Phase 2: Mode dispatch — branch on --auto vs synchronous
Phase 3a: Auto-merge path (--auto) — gh pr merge --auto; return in <5s
Phase 3b: Synchronous path (default) — pre-checks; gh pr merge; fetch mergeSha
Phase 4: Result emission — single-line JSON to stdout; exit with code
Phase 0 — Argument Parsing and Validation
Step 0.1 — Parse Flags
Extract the five flags from the command line in the order they appear. Assign defaults from the parameters table. Stop and emit PR_NOT_FOUND (exit 1) if --pr is absent, empty, or not a positive integer.
Log: "[Phase 0] pr={N} strategy={STRATEGY} deleteBranch={BOOL} auto={BOOL} waitTimeoutMin={N}"
Step 0.2 — Validate Enumerations
- If
--strategyis present but not in{merge, squash, rebase}, abort withINVALID_STRATEGY(exit code 1 class). - If
--wait-timeout-minis present and outside[1, 600], abort withINVALID_TIMEOUT(exit code 1 class). - If both validations pass, proceed to Phase 1.
Log: "[Phase 0] arguments validated"
Phase 1 — PR State Inspection and Idempotency
Step 1.1 — Single gh pr view Call
Execute exactly ONE state-fetching call (performance contract: < 5s in the --auto path depends on this being the only gh invocation before merge):
gh pr view {PR_NUMBER} --json number,state,mergeable,reviewDecision,statusCheckRollup,headRefName,baseRefName
Capture stdout into a local variable prState. If the call fails with a non-zero exit:
- gh exit 1 with message containing "Could not resolve" or "not found" → abort
PR_NOT_FOUND(exit 1). - Any other gh failure → abort with a generic error carrying the gh stderr as message.
Log: "[Phase 1] fetched state for PR #{N}: state={STATE} mergeable={MERGEABLE} reviewDecision={DECISION}"
Step 1.2 — Idempotency Short-Circuit
Apply the following decision table BEFORE any further processing:
state |
Action | Response |
|---|---|---|
MERGED |
Emit success envelope with merged=true, prState=MERGED, waitedSec=0, autoEnabled=false. Exit 0. |
Idempotent no-op. |
CLOSED |
Abort with PR_CLOSED (exit 2). |
— |
OPEN |
Continue to Phase 2. | — |
Log (when short-circuiting): "[Phase 1] PR #{N} already in terminal state {STATE}; idempotent exit"
Phase 2 — Mode Dispatch
Branch on the --auto flag value recorded in Phase 0:
--auto |
Next Phase |
|---|---|
true |
Phase 3a (Auto-merge path) |
false |
Phase 3b (Synchronous path) |
Phase 3a — Auto-Merge Path (--auto)
Step 3a.1 — Invoke gh pr merge --auto
Build the command by appending flags in this order:
gh pr merge {PR_NUMBER} --{STRATEGY} --auto [--delete-branch]
--{STRATEGY}is one of--merge,--squash,--rebase.--delete-branchis appended ONLY when--delete-branch true(the default).
Execute the command. The performance contract is strict: this step MUST return in < 5s. Do NOT poll, do NOT wait.
Step 3a.2 — Interpret Result
gh exit |
Interpretation |
|---|---|
| 0 | Auto-merge enabled. Emit {merged:false, prState:OPEN, waitedSec:0, autoEnabled:true}. Exit 0. |
| Non-zero, message contains "Pull request is in clean state" | PR was already mergeable and was merged synchronously by GitHub. Refetch state (Phase 1), emit {merged:true, mergeSha:..., prState:MERGED, waitedSec:0, autoEnabled:false}. Exit 0. |
| Non-zero, message contains "auto-merge is not allowed" | Repo does not permit auto-merge. Emit error with clear message and exit with CI_FAILING-adjacent code 4 (repo misconfiguration; caller should enable auto-merge in repo settings). |
| Non-zero, other | Emit generic error carrying gh stderr. Exit 1. |
Log: "[Phase 3a] auto-merge enabled for PR #{N}; skill returning"
Phase 3b — Synchronous Path (Default)
Step 3b.1 — Pre-Check: mergeable
Inspect the mergeable field captured in Phase 1:
| Value | Action |
|---|---|
MERGEABLE |
Proceed to Step 3b.2. |
CONFLICTING |
Abort with MERGE_CONFLICT (exit 5). |
UNKNOWN |
Enter polling loop (Step 3b.1a). |
Step 3b.1a — Polling Loop for UNKNOWN
Loop with a fixed 10-second sleep between iterations. Break when mergeable != UNKNOWN or total elapsed time exceeds --wait-timeout-min minutes:
elapsed=0
timeout_sec=$(( WAIT_TIMEOUT_MIN * 60 ))
while [ "$mergeable" = "UNKNOWN" ] && [ "$elapsed" -lt "$timeout_sec" ]; do
sleep 10
elapsed=$(( elapsed + 10 ))
mergeable=$(gh pr view {N} --json mergeable --jq '.mergeable')
done
If the loop exits with mergeable == UNKNOWN, abort with TIMEOUT (exit 6). Record waitedSec = elapsed.
Step 3b.2 — Pre-Check: reviewDecision
| Value | Action |
|---|---|
APPROVED |
Proceed to Step 3b.3. |
REVIEW_REQUIRED | CHANGES_REQUESTED | null |
Abort with NOT_APPROVED (exit 3). |
Step 3b.3 — Pre-Check: statusCheckRollup
Parse the statusCheckRollup array. A "failing" check has conclusion in {FAILURE, ERROR, TIMED_OUT, CANCELLED} OR status == IN_PROGRESS past the timeout.
| Summary | Action |
|---|---|
All checks conclusion == SUCCESS OR status == COMPLETED && conclusion == NEUTRAL |
Proceed to Step 3b.4. |
| Any failing check | Abort with CI_FAILING (exit 4). |
Any check still IN_PROGRESS |
Enter polling loop identical to Step 3b.1a, re-fetching statusCheckRollup until all checks complete or timeout. On timeout, abort TIMEOUT (exit 6). |
Log: "[Phase 3b] pre-checks passed: mergeable=MERGEABLE reviewDecision=APPROVED checks=all-green"
Step 3b.4 — Invoke gh pr merge (Synchronous)
Build and execute the command (NO --auto flag):
gh pr merge {PR_NUMBER} --{STRATEGY} [--delete-branch]
Capture stdout and stderr. On non-zero exit:
- stderr contains "not mergeable" → abort
MERGE_CONFLICT(exit 5). - stderr contains "approval" → abort
NOT_APPROVED(exit 3). - other → abort with generic error carrying stderr.
Step 3b.5 — Fetch Merge SHA
After a successful gh pr merge, refetch PR state to capture the merge commit SHA:
gh pr view {PR_NUMBER} --json mergeCommit --jq '.mergeCommit.oid'
Record as mergeSha. If the field is null (rare race), retry after 2 seconds once; if still null, emit success with mergeSha=null and a warning log.
Step 3b.6 — Emit Result
Emit to stdout:
{"merged":true,"mergeSha":"{SHA}","prState":"MERGED","waitedSec":{N},"autoEnabled":false}
Exit 0.
Log: "[Phase 3b] PR #{N} merged synchronously; mergeSha={SHA} waitedSec={N}"
Phase 4 — Result Emission
All exit paths (success and failure) emit EXACTLY one line of JSON to stdout and exit with the code from the table in "Output Contract > Exit Codes". Error envelopes carry:
{"merged":false,"prState":"{STATE}","waitedSec":{N},"autoEnabled":false,"errorCode":"{CODE}","message":"{HUMAN_MESSAGE}"}
Stderr SHOULD carry the [Phase N] ... log lines; stdout MUST carry only the single JSON envelope. This separation allows callers to pipe stdout | jq without contamination.
Examples
Example 1 — Happy Path (Synchronous, merge strategy)
/x-merge-pr --pr 123
Result (stdout):
{"merged":true,"mergeSha":"a1b2...","prState":"MERGED","waitedSec":3,"autoEnabled":false}
Example 2 — Squash Strategy with Auto-Merge
/x-merge-pr --pr 456 --strategy squash --auto
Result (returns in <5s):
{"merged":false,"prState":"OPEN","waitedSec":0,"autoEnabled":true}
GitHub will merge asynchronously when CI + approvals pass.
Example 3 — Rebase Strategy, Preserve Branch
/x-merge-pr --pr 789 --strategy rebase --delete-branch false
Result (stdout):
{"merged":true,"mergeSha":"c3d4...","prState":"MERGED","waitedSec":5,"autoEnabled":false}
Example 4 — Idempotent Re-Invocation
/x-merge-pr --pr 123 # already merged by previous run
Result (exits 0 immediately, no gh pr merge call):
{"merged":true,"prState":"MERGED","waitedSec":0,"autoEnabled":false}
Example 5 — Error: Not Approved
/x-merge-pr --pr 123
Result (exit 3):
{"merged":false,"prState":"OPEN","waitedSec":0,"autoEnabled":false,"errorCode":"NOT_APPROVED","message":"PR #123 not approved"}
Error Envelope
| Scenario | Exit | Error Code |
|---|---|---|
--pr missing, zero, negative, non-numeric |
1 | PR_NOT_FOUND |
--strategy not in {merge, squash, rebase} |
1 | INVALID_STRATEGY |
--wait-timeout-min not in [1, 600] |
1 | INVALID_TIMEOUT |
gh pr view returns "not found" |
1 | PR_NOT_FOUND |
PR state is CLOSED (not merged) |
2 | PR_CLOSED |
reviewDecision != APPROVED (synchronous mode) |
3 | NOT_APPROVED |
statusCheckRollup has failing checks (synchronous mode) |
4 | CI_FAILING |
mergeable == CONFLICTING |
5 | MERGE_CONFLICT |
mergeable == UNKNOWN past timeout (synchronous mode) |
6 | TIMEOUT |
Integration Notes
| Consumer | Relationship | Usage |
|---|---|---|
x-create-pr |
Invokes this skill when --auto-merge <strategy> is passed (RULE-002 auto-merge default ON) |
After creating the PR, forwards --strategy + --auto to x-merge-pr to enable native GitHub auto-merge. |
x-implement-epic |
Invokes this skill in Phase 1.3b (merge of epic PRs to epic/XXXX or develop) |
Replaces the previous ~80 lines of inline gh pr merge + polling. Calls with --strategy merge --auto by default. |
x-manage-pr-merge-train |
Does NOT call this skill directly | Uses its own train-specific merge orchestration; however, both skills share the same exit-code semantics for consistency across the /x-pr-* family. |
Called Tools
gh pr view(one call minimum, two in the auto-merge "clean state" edge case)gh pr merge(one call in synchronous path; one call in--autopath)sleep(only in theUNKNOWN/IN_PROGRESSpolling loop)
No git operations are performed by this skill — branch deletion is delegated to gh pr merge --delete-branch.
Testing Contract
Unit Tests (mocked gh CLI)
idempotent_alreadyMerged_returnsMergedTrue—gh pr viewreturnsstate=MERGED; skill exits 0 with{merged:true, waitedSec:0}.closed_pr_returnsPrClosed—gh pr viewreturnsstate=CLOSED; skill exits 2 withPR_CLOSED.sync_happy_path_mergeStrategy— all pre-checks pass;gh pr merge --mergesucceeds; skill emits{merged:true, mergeSha:...}.sync_happy_path_squashStrategy— same as above with--strategy squash; verifies--squashflag propagation.sync_happy_path_rebaseStrategy— same with--strategy rebase; verifies--rebaseflag propagation.sync_notApproved_exitsNotApproved—reviewDecision=REVIEW_REQUIRED; skill exits 3 withNOT_APPROVED.sync_ciFailing_exitsCiFailing—statusCheckRollupcontains aFAILUREconclusion; skill exits 4.sync_mergeConflict_exitsMergeConflict—mergeable=CONFLICTING; skill exits 5.sync_timeout_exitsTimeout—mergeable=UNKNOWNpersists past--wait-timeout-min=1; skill exits 6 after ~60s.auto_mode_enablesAutoMerge—--auto→gh pr merge --autoreturns 0; skill emits{autoEnabled:true, merged:false}in <5s.auto_mode_cleanStateEdgeCase—gh pr merge --autoreturns "clean state"; skill refetches and reports as synchronous merge.deleteBranchFalse_doesNotAppendFlag—--delete-branch false; verifygh pr mergeinvocation does NOT include--delete-branch.invalidStrategy_exitsInvalidStrategy—--strategy invalid; skill exits 1 withINVALID_STRATEGYbefore anyghcall.invalidTimeout_exitsInvalidTimeout—--wait-timeout-min 0or--wait-timeout-min 601; skill exits 1 withINVALID_TIMEOUT.missingPr_exitsPrNotFound— no--pr; skill exits 1 withPR_NOT_FOUND.
Smoke Test (gated by GITHUB_TOKEN)
Single end-to-end test (PrMergeSmokeTest) that:
- Creates a disposable PR on a fixture repository branch.
- Invokes
/x-merge-pr --pr {N} --auto. - Verifies
autoEnabled=trueand exit 0. - Waits up to 60s for GitHub to merge asynchronously.
- Cleans up the test branch.
Skipped when GITHUB_TOKEN is absent; reported as SKIPPED to avoid failing CI in contributor forks.
Coverage Targets
- Line coverage: ≥ 95% (skill-level logic exercised by the 15 unit scenarios above).
- Branch coverage: ≥ 90% (each decision table branch in Phases 1, 3a, 3b covered).
Forbidden
- NEVER invoke
git mergedirectly — the skill MUST route all merges throughgh pr mergeto preserve GitHub-side history and branch-deletion side effects. - NEVER bypass pre-checks in synchronous mode — even on repeat invocations after a CI flake.
- NEVER emit multiple JSON envelopes to stdout — callers rely on single-line parsing.
- NEVER exit 0 on any error condition — the exit-code table is a hard contract.
- NEVER poll
gh pr mergeitself — onlygh pr viewis polled.gh pr mergeis a single synchronous call per phase.
Status
- Story: story-0049-0003 (epic-0049, "x-merge-pr extraction from x-implement-epic Phase 1.3b")
- Parent Contract: RULE-002 (auto-merge default ON), RULE-004 (preserve history), RULE-005 (thin orchestrator)
- Dependencies: none (first skill in its sub-tree of epic-0049)
- Downstream: story-0049-0016 (
x-create-pr --auto-mergepropagation), story-0049-0018 (x-implement-epicrefactor)
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.