Back to Details

merge-queue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Merge Queue

Merge Queue

Take a set of pull requests, queue them, and drive each one to a merged state the way GitHub's Merge Queue would — sequentially, always against the freshest base. Resolve the things that block a merge one at a time and autonomously: approve, update the branch, resolve simple conflicts, fix simple CI failures. The caller is handing this off and leaving; your job is to finish everything you safely can and leave a clean report of whatever genuinely needs a human.
接收一组pull requests（PR），将其加入队列，并按照GitHub Merge Queue的方式逐个推进至合并状态——按顺序处理，始终基于最新的基准分支。逐个自动解决合并障碍：审批、更新分支、解决简单冲突、修复简单CI失败。发起者会将任务交付后离开；你的工作是安全完成所有可处理的事项，并针对确实需要人工介入的内容提交清晰报告。

The Deal (read before doing anything)

注意事项（执行前必读）

  • Gate first, work second. Assess every PR before you touch any of them. If none are mergeable-now or auto-resolvable, STOP and ask the user — do not start half-work.
  • Don't block on lunch. Once at least one PR is actionable, proceed without asking for confirmation. A PR that turns out to need human judgment is deferred to the final report, not a reason to halt the whole run.
  • Autonomy has a boundary. You resolve mechanical blockers. Anything requiring a product/logic decision — a semantic merge conflict, a real test failure, marking a draft ready — is deferred, never guessed at.
  • Everything here is outward-facing and hard to undo (approvals, pushes, merges). The PR numbers in 
    args
    are the authorization to merge those PRs and nothing else.
  • Stay responsive. The slow parts (CI runs, branch recompute) run as background tasks so the session is always free to accept new PRs into the queue and to make progress on other PRs meanwhile. You never sit blocked on a single PR.
  • 先检查，再执行。在处理任何PR之前先评估所有PR。如果没有任何PR可立即合并或可自动解决障碍，请停止操作并询问用户——不要半途而废。
  • 不要因等待停滞。只要至少有一个PR可处理，无需等待确认即可继续。若某个PR最终需要人工判断，将其推迟到最终报告中，而非终止整个流程。
  • 自动化有边界。仅解决机械性障碍。任何需要产品/逻辑决策的事项——语义合并冲突、真实测试失败、将草稿标记为就绪——都需推迟处理，绝不擅自猜测。
  • 所有操作均对外可见且难以撤销（审批、推送、合并）。
    args
    中的PR编号是合并这些特定PR的授权，不得用于其他PR。
  • 保持响应性。耗时操作（CI运行、分支重新计算）作为后台任务执行，确保会话始终可接受新PR加入队列，同时推进其他PR的处理。绝不要因单个PR而停滞。

The Queue Board (render it every turn)

队列看板（每次操作都要展示）

The board is the single source of truth and the user's whole window into progress. Keep it in a state file so it survives context compaction, and re-render it in your reply on every turn where anything changed:
bash
board="$(git rev-parse --show-toplevel)/.git/merge-queue-board.md"   # inside .git → never committed
The board is always a table plus a progress line, with exactly the columns the user tracks:
undefined
看板是唯一的事实来源，也是用户了解进度的窗口。将其保存在状态文件中，确保在上下文压缩后仍能保留，并且每次有变更时都要在回复中重新渲染：
bash
board="$(git rev-parse --show-toplevel)/.git/merge-queue-board.md"   # inside .git → never committed
看板始终包含一个表格和一条进度线，列数与用户关注的内容完全一致：
undefined

Merge Queue — 2/5 done (40%) · 1 in progress · 1 deferred

Merge Queue — 2/5 done (40%) · 1 in progress · 1 deferred

#PRBranchSummaryVerdict
1#12feat/loginAdd OAuth login✅ merged
2#13fix/nav-crashFix null nav crash✅ merged
3#14chore/bump-depsBump deps🔧 updating branch (bg)
4#15feat/export-csvCSV export⏳ queued
5#16feat/redesignDashboard redesign⏭️ deferred: semantic conflict

- **Verdict** column is the merge-viability judgment + current action. Vocabulary:
  `✅ merged` · `🔵 mergeable now` · `🔧 <action> (bg)` (approving / updating branch /
  resolving conflict / fixing lint / re-running CI) · `⏳ queued` · `⏭️ deferred: <reason>`
  · `⛔ blocked: <reason>` (gate failed, needs user).
- **Progress line** = merged ÷ total as a percentage, plus counts of in-progress and
  deferred. Update it whenever a PR changes state.
- Rewrite the board file, then paste the current table into your reply. This is not
  optional decoration — it is how the user checks in after lunch.
#PRBranchSummaryVerdict
1#12feat/loginAdd OAuth login✅ merged
2#13fix/nav-crashFix null nav crash✅ merged
3#14chore/bump-depsBump deps🔧 updating branch (bg)
4#15feat/export-csvCSV export⏳ queued
5#16feat/redesignDashboard redesign⏭️ deferred: semantic conflict

- **Verdict**列是合并可行性判断+当前操作。词汇说明：
  `✅ merged` · `🔵 mergeable now` · `🔧 <action> (bg)`（审批中/更新分支中/解决冲突中/修复代码格式中/重新运行CI中）· `⏳ queued` · `⏭️ deferred: <reason>`
  · `⛔ blocked: <reason>`（检查未通过，需用户处理）。
- **进度线** = 已合并数 ÷ 总数的百分比，加上进行中及推迟处理的PR数量。每当PR状态变更时更新。
- 重写看板文件，然后将当前表格粘贴到回复中。这不是可选的装饰——这是用户在休息后查看进度的方式。

Steps (follow strictly)

步骤（严格遵循）

1. Parse input and preflight

1. 解析输入并预检查

Read PR numbers from 
args
(space/comma separated). If empty, ask which PRs. Then:
bash
gh auth status          # must be authenticated
gh repo view --json nameWithOwner,defaultBranchRef -q '.nameWithOwner, .defaultBranchRef.name'
Work in a clean checkout of this repo (no uncommitted changes — 
git status
clean). If the working tree is dirty, STOP and tell the user; you must not stash their work.
从
args
中读取PR编号（空格/逗号分隔）。若为空，询问用户要处理哪些PR。然后执行：
bash
gh auth status          # must be authenticated
gh repo view --json nameWithOwner,defaultBranchRef -q '.nameWithOwner, .defaultBranchRef.name'
在仓库的干净检出目录中工作（无未提交变更——
git status
显示干净）。若工作区有脏文件，请停止操作并告知用户；不得暂存用户的工作内容。

2. Assess every PR (the gate)

2. 评估所有PR（检查环节）

For each PR, pull the state in one shot:
bash
gh pr view <n> --json number,title,isDraft,mergeable,mergeStateStatus,reviewDecision,\
headRefName,baseRefName,statusCheckRollup,author,url
Map 
mergeStateStatus
+ review state to a class:
StateMeaningClass
CLEAN
up to date, approved, checks greenMerge now
BEHIND
branch out of date with baseAuto-resolve → update branch
BLOCKED
(only missing approval)		needs a reviewAuto-resolve → approve
UNSTABLE
/ failing checks		a check is redInspect (§4.3) — simple fix or defer
DIRTY
merge conflictInspect (§4.2) — simple resolve or defer
DRAFT
/ 
isDraft
draft PRDefer — human marks it ready
UNKNOWN
GitHub still computingre-poll a few times before classifying
Write each PR — number, branch (
headRefName
), a one-line summary (the title), and its verdict — into the Queue Board and render it. This is the plan the user sees before walking away.
Gate decision: if every PR lands in Defer (nothing is Merge-now or Auto-resolve), STOP. The board shows every row as 
⛔ blocked
/ 
⏭️ deferred
with reasons; ask the user how to proceed. Otherwise continue.
针对每个PR，一次性获取其状态：
bash
gh pr view <n> --json number,title,isDraft,mergeable,mergeStateStatus,reviewDecision,\
headRefName,baseRefName,statusCheckRollup,author,url
将
mergeStateStatus
+ 评审状态映射为类别：
StateMeaningClass
CLEAN
分支已更新、已审批、检查通过立即合并
BEHIND
分支落后于基准分支自动解决 → 更新分支
BLOCKED
（仅缺少审批）		需要评审自动解决 → 审批
UNSTABLE
/ 检查失败		某项检查未通过检查（§4.3）——简单修复或推迟处理
DIRTY
合并冲突检查（§4.2）——简单解决或推迟处理
DRAFT
/ 
isDraft
草稿PR推迟处理——需人工标记为就绪
UNKNOWN
GitHub仍在计算状态重新轮询几次后再分类
将每个PR的编号、分支（
headRefName
）、单行摘要（标题）及其判断结果写入队列看板并渲染。这是用户离开前看到的计划。
检查决策：如果所有PR都属于推迟处理（没有可立即合并或自动解决的PR），请停止操作。看板中每一行都会显示
⛔ blocked
/ 
⏭️ deferred
及原因；询问用户如何继续。否则继续执行。

3. Order the queue

3. 排序队列

Process PRs sharing a base branch sequentially, in the order given (respect explicit dependencies if the user stated any). Sequential is the whole point: each PR is brought up to date after the previous one merges, so you are always testing the real combined result — exactly what a merge queue does. Different base branches are independent lanes.
按用户给定的顺序依次处理共享同一基准分支的PR（若用户明确说明依赖关系，则遵循依赖顺序）。依次处理是核心：每个PR都会在前一个PR合并后更新至最新状态，因此始终测试真实的组合结果——这正是合并队列的作用。不同基准分支为独立处理通道。

4. Drive each PR to merged (in the background)

4. 推进每个PR至合并状态（后台执行）

The blocking waits here — CI re-running after a push, 
update-branch
recomputing — take minutes. Run them as background tasks (
Bash
with 
run_in_background: true
) so you are not stuck: kick off the wait, mark the PR 
🔧 <action> (bg)
on the board, and use the freed session to advance the next independent PR, refresh the board, or take new PRs from the user. When a background command finishes you're re-invoked with its result — reconcile it into the board then. Do not foreground-
sleep
to wait; a background poll loop is the pattern (e.g. 
until gh pr checks <n> | grep -qv pending; do sleep 20; done
).
For the current PR, resolve blockers one at a time, re-checking state after each fix (a fix often changes 
mergeStateStatus
). Update the board's Verdict after each transition. Loop until CLEAN or deferred.
此处的阻塞等待——推送后重新运行CI、
update-branch
重新计算——需要数分钟时间。将这些操作作为后台任务执行（
Bash
中设置
run_in_background: true
），避免停滞：启动等待操作，在看板上将PR标记为
🔧 <action> (bg)
，利用空闲会话推进下一个独立PR、刷新看板或接收用户的新PR。当后台命令完成后，会重新调用并返回结果——将结果同步到看板中。不要通过前台
sleep
等待；应使用后台轮询循环（例如
until gh pr checks <n> | grep -qv pending; do sleep 20; done
）。
针对当前PR，逐个解决障碍，每次修复后重新检查状态（修复通常会改变
mergeStateStatus
）。每次状态转换后更新看板的Verdict列。循环直到状态为CLEAN或推迟处理。

4.1 Out of date (
BEHIND
)

4.1 分支落后（
BEHIND
）

bash
gh pr update-branch <n>          # merges base into the PR branch server-side
Then wait for checks to re-run (§4.4). If update-branch itself reports a conflict, treat as §4.2.
bash
gh pr update-branch <n>          # merges base into the PR branch server-side
然后等待检查重新运行（§4.4）。若update-branch本身报告冲突，则按§4.2处理。

4.2 Conflict (
DIRTY
)

4.2 合并冲突（
DIRTY
）

Resolve locally against the current base:
bash
git fetch origin
git switch <headRefName> && git pull
git merge origin/<baseRefName>
  • Simple — conflicts only in lockfiles / generated files (regenerate them), or trivial non-overlapping hunks: resolve, commit, 
    git push
    .
  • Semantic — overlapping edits to real source/logic: defer. Abort (
    git merge --abort
    ), record it for the report. Do not guess at intent.
在本地针对当前基准分支解决冲突：
bash
git fetch origin
git switch <headRefName> && git pull
git merge origin/<baseRefName>
  • 简单冲突——仅在锁文件/生成文件中存在冲突（重新生成即可），或无关紧要的非重叠代码块：解决冲突、提交、
    git push
    。
  • 语义冲突——对真实源码/逻辑的重叠修改：推迟处理。中止合并（
    git merge --abort
    ），记录到报告中。绝不猜测意图。

4.3 Failing CI (
UNSTABLE
/ red checks)

4.3 CI失败（
UNSTABLE
/ 检查未通过）

bash
gh pr checks <n>                 # see which check failed
Only simple, mechanical failures are in scope:
  • Formatting / lint autofix (
    mise run fmt
    , 
    prettier -w
    , 
    eslint --fix
    , 
    cargo fmt
    , 
    gofmt
    — whatever the repo uses), commit and push.
  • Stale generated files / lockfiles → regenerate, push.
  • A single obviously-flaky check → re-run once (
    gh run rerun --failed
    ).
Everything else — real unit/integration failures, type errors needing code changes, security scans — is defer. You are not debugging product logic here.
bash
gh pr checks <n>                 # see which check failed
仅处理简单、机械性失败：
  • 格式/代码规范自动修复（
    mise run fmt
    , 
    prettier -w
    , 
    eslint --fix
    , 
    cargo fmt
    , 
    gofmt
    ——使用仓库对应的工具），提交并推送。
  • 过期的生成文件/锁文件 → 重新生成、推送。
  • 明显不稳定的单个检查 → 重新运行一次（
    gh run rerun --failed
    ）。
其他所有情况——真实的单元/集成测试失败、需要修改代码的类型错误、安全扫描失败——都需推迟处理。此处不负责调试产品逻辑。

4.4 Missing approval (
BLOCKED
on review)

4.4 缺少审批（
BLOCKED
等待评审）

bash
gh pr review <n> --approve -b "Approved via merge-queue"
If you are the PR author you cannot self-approve, and branch protection may require another party — in that case defer (record "needs approval from someone else").
bash
gh pr review <n> --approve -b "Approved via merge-queue"
若你是PR作者，则无法自我审批，且分支保护规则可能需要其他人员审批——这种情况下推迟处理（记录“需要他人审批”）。

4.5 Merge

4.5 合并

When the PR is CLEAN, merge with the repo's convention (check 
git log
/ repo settings; default squash):
bash
gh pr merge <n> --squash --delete-branch
git switch <baseRefName> && git pull --ff-only   # refresh local base for the next PR
当PR状态为CLEAN时，按照仓库的约定合并（查看
git log
/ 仓库设置；默认使用 squash 合并）：
bash
gh pr merge <n> --squash --delete-branch
git switch <baseRefName> && git pull --ff-only   # refresh local base for the next PR

5. Advance the queue (and keep taking additions)

5. 推进队列（并持续接收新PR）

After a merge, re-assess the remaining PRs from §2 — the merge you just did usually puts the next one 
BEHIND
or, occasionally, 
DIRTY
. Bump the progress line and continue until the queue is empty.
New PRs are welcome any time. If the user hands you more PR numbers mid-run, append them as new rows, assess them (§2), and slot them into the queue — never make the user wait for the current PR to finish before their addition is accepted. Because the slow work is backgrounded, there is always headroom to do this.
合并完成后，重新评估剩余PR的状态（§2）——刚刚完成的合并通常会导致下一个PR变为
BEHIND
，偶尔会变为
DIRTY
。更新进度线并继续处理，直到队列为空。
随时欢迎添加新PR。若用户在流程中提供更多PR编号，将其作为新行追加到队列中，评估其状态（§2）并插入队列——绝不要让用户等待当前PR完成后再添加新PR。由于耗时操作在后台执行，始终有处理空间。

6. Report

6. 报告

The board is the running report — the user can read it at any point. When the queue drains (or stalls entirely on deferrals), post a final render plus the specifics:
  • ✅ Merged (with PR numbers/links)
  • 🔧 Auto-resolved and merged, with what you did (approved / updated / fixed lint / …)
  • ⏭️ Deferred — each with the concrete blocker and the human action needed
  • Anything you re-ran or pushed to their branches
看板本身就是实时报告——用户可随时查看。当队列处理完成（或因推迟处理完全停滞）时，发布最终看板渲染结果及详细信息：
  • ✅ 已合并（包含PR编号/链接）
  • 🔧 自动解决并合并，说明处理内容（审批/更新分支/修复代码格式/……）
  • ⏭️ 推迟处理——每个PR的具体障碍及所需人工操作
  • 所有重新运行的检查或推送到分支的内容

Red Flags — STOP or DEFER, do not power through

危险信号——停止或推迟处理，不要强行推进

  • You are about to resolve a conflict in real source code by choosing a side. Defer.
  • A test failed and you are editing product code to make it pass. Out of scope — defer.
  • Tempted to mark a draft "ready" or dismiss a requested change. That is the human's call — defer.
  • --force
    / 
    --admin
    / bypassing branch protection.     Never. If protection blocks the merge, that is a deliberate gate — defer it.
  • Nothing was actionable but you started editing anyway. The gate in §2 means STOP.
  • 你要通过选择某一方来解决真实源码中的冲突。推迟处理。
  • 测试失败，你要修改产品代码使其通过。超出范围——推迟处理。
  • 想要将草稿标记为“就绪”或驳回评审意见。这是人工决策——推迟处理。
  • 使用
    --force
    / 
    --admin
    / 绕过分支保护规则    。绝不允许。若保护规则阻止合并，这是故意设置的检查——推迟处理。
  • 没有可处理的PR，但你仍开始编辑。§2中的检查环节要求停止操作。

Gotchas

注意事项

  • Dirty working tree: this skill pushes commits and switches branches. Refuse to run if 
    git status
    isn't clean — you must never stash or clobber the user's local work.
  • Self-approval is impossible: GitHub rejects approving your own PR. In a solo repo the approval blocker is unresolvable autonomously — surface it rather than looping.
  • mergeStateStatus
    lags    : after any push/update it goes 
    UNKNOWN
    while GitHub recomputes. Poll a few times (short sleeps) before deciding it's blocked.
  • UNSTABLE
    can still be mergeable    : it means a non-required check is red. If required checks are green and policy allows, it may merge as-is — don't "fix" a check that isn't actually gating.
  • Sequential, not parallel: never update/merge two PRs on the same base concurrently — you'd be testing a combination that won't exist. One at a time, re-based after each merge.
  • Re-run flaky once, not forever: a check that fails twice is not flaky. Defer it.
  • Background ≠ concurrent same-base merges: backgrounding the waits is fine and keeps you responsive, but you still merge one PR per base at a time. Never let two same-base PRs reach 
    gh pr merge
    in parallel — the queue would test a combination that won't exist.
  • The board must survive compaction: it lives in 
    .git/merge-queue-board.md
    , not just in your context. On resuming, read that file back before rendering so no progress is lost.
  • 脏工作区：该技能会推送提交并切换分支。若
    git status
    显示不干净，拒绝运行——绝不要暂存或覆盖用户的本地工作内容。
  • 无法自我审批：GitHub拒绝审批自己的PR。在单人仓库中，审批障碍无法自动解决——需明确告知用户，而非循环尝试。
  • mergeStateStatus
    存在延迟    ：推送/更新后，状态会变为
    UNKNOWN
    ，直到GitHub重新计算。在判定为阻塞前，重新轮询几次（短时间睡眠）。
  • UNSTABLE
    仍可能可合并    ：表示某个非必填检查未通过。若必填检查已通过且策略允许，可直接合并——不要“修复”并非真正阻塞的检查。
  • 依次处理，而非并行：绝不要同时更新/合并同一基准分支上的两个PR——你会测试一个不存在的组合。逐个处理，每次合并后重新基准化。
  • 不稳定检查仅重新运行一次，而非无限次：连续失败两次的检查并非不稳定。推迟处理。
  • 后台执行≠同一基准分支并行合并：将等待操作后台执行是可行的，可保持响应性，但仍需逐个合并同一基准分支的PR。绝不要让两个同一基准分支的PR同时进入
    gh pr merge
    环节——队列会测试一个不存在的组合。
  • 看板必须在压缩后保留：看板存储在
    .git/merge-queue-board.md
    中，而非仅存在于上下文。恢复会话时，先读取该文件再渲染，避免丢失进度。