Mergepatrol 是一个标签驱动的合并队列,用于让仓库中的拉取请求(PR)有序地进入队列并自动完成合并。仓库中的 PR 通过 Mergepatrol 落地,手动合并或直接向默认分支推送会与队列产生竞争。
用途
- 为默认分支及 .mergepatrol/mergepatrol.yml 中 branches 列出的每个分支维护队列;PR 或来自 gh stack 的 PR 堆叠进入其目标分支的队列。
- 合并到其他分支(例如手工堆叠在另一 PR 分支上的 PR)会被扣留。
- 重定向已排队的 PR 会把它移到另一分支队列的末尾。
主要能力
- 标签触发:在 .mergepatrol/mergepatrol.yml 中配置触发标签,默认 mergepatrol。给 PR 添加该标签即入队;移除则离队并取消其运行。<label>:priority 置于队首;<label>:failed 由 Mergepatrol 在弹出 PR 时设置。
- MCP 集成:连接 mergepatrol MCP 服务器后,可用 queue_pull(支持 priority 置于队首)、dequeue_pull、pull_status、list_queue 等工具替代标签操作,它们以所连接用户或机器人的身份修改相同标签。pull_status 直接读取 PR 所处位置,无需解析评论。服务器其他工具对应 Mergepatrol 仪表盘的功能,例如审查 PR 或读取队列弹出原因。
- 队列处理:将 PR 变基到其基线分支,可与其他排队 PR 成批测试;由代理解决冲突,运行仓库的校验命令,等待必需检查,再按仓库默认合并方式合并。必需检查失败时代理会向 PR 分支提交修复并重跑检查,最多若干次,除非 fix_ci 关闭。
- 堆叠:一个堆叠是队列中的一个条目。给其中任一 PR 打标签即整栈入队,整栈等待所有 PR 就绪;变基时重写每一层,并一次性全部合并(全有或全无)。弹出堆叠时其中每个 PR 都会获得 <label>:failed。
- 变基会重写 PR 分支,修复会新增提交;向已排队 PR 推送更多提交前应先 fetch 并基于远程分支变基,推送会使 Mergepatrol 重新开始该 PR。
状态读取
Mergepatrol 在每个排队 PR 上维护一条评论,内容为:
- On hold:PR 是草稿、等待必需审查或存在要求修改;评论会说明原因,保留位置,待 GitHub 显示就绪后运行。
- Under review:默认开启自动审查,代理在 PR 取得位置前先审查。确定应修改的内容以行内审查评论形式发回作者;所有审查线程解决后 PR 继续,无需人工批准。仅就作者无法决定的问题(范围或产品判断、访问权限、仓库外改动)询问人工。MCP 的 get_agent_review 可读取审查。
- Ejected:变基、检查或合并失败,评论说明原因;触发标签被移除,<label>:failed 被添加。修复原因、推送后重新添加标签。
- Merged:完成,队列标签被移除。
排队之后:处理审查
入队并非工作终点。构建 PR 者应持续跟进,直到合并、被弹出或仅剩需人工项。逐一处理每条审查评论:修复或附理由驳回,并解决线程。存在未解决线程时 PR 被扣留,全部解决后进入队列。仅对无法从代码、仓库和用户信息中决定的事项询问人工。
什么算作评论
每个未解决审查线程都算一条评论:Mergepatrol 审查发现的每条会阻塞 PR 的发现各成一线程;人类审查者或其他机器人的线程;以及请求修改的审查和提出修改请求的顶层评论。审查已清除的发现和其栏下备注无需处理。Mergepatrol 跨推送对同一发现保持一条线程:再次发现时在该线程回复并重新打开;发现已修复或回复在代码中成立时,它自行解决线程。只应基于 PR 当前 head 的审查作出处理,旧 head 的审查可能在你推送后到达并已过时。
评论状态
- open:尚未处理。阅读并查看所指代码,然后修复、驳回或标记为 needs-human。
- fixed:已推送的提交实现了要求。在线程回复提交短 SHA 和一行变更说明后解决;仅在推送后解决。
- dismissed:不适用,且有代码可证明。在线程回复理由和证据(文件与行号、测试、文档),然后解决。
- needs-human:仅人工可决定。回复所需决定和选项,@相关人员,保持未解决。
以下情况才属于 needs-human:PR 应做什么或包含什么(范围)、产品或设计判断、你没有的凭据或访问权限、本仓库之外的改动,或审查者在驳回后重新打开线程。“我不确定”不属于此类,应继续阅读代码、运行或先询问审查者。审查保持对抗性:下次推送会读取你的回复,理由在代码中不成立时会重新打开已驳回线程。
循环流程
- 等待当前 head 的审查;待定或运行中每隔几分钟轮询 pull_status、get_agent_review 或 Mergepatrol 评论,期间不要推送。
- 列出未解决线程并与台账匹配;重新打开的线程视为新一轮。
- 将每个 open 处理为 fixed、dismissed 或 needs-human;尽量合并较少提交。
- 如有修复则推送一次;先 fetch 并变基到远程分支。
- 在每个已处理线程中回复,并解决 fixed 与 dismissed 的线程;无回复不得解决。
- 更新台账。
- 推送后回到步骤 1;当只剩 needs-human 线程未解决,或 PR 已合并/弹出时停止。被弹出的 PR 修复原因、推送并重新添加标签。
无未解决线程且无需人工处理时,PR 自动进入队列,无需人工批准。
审查发现与限制
- 不要对你自己构建的 PR 调用 answer_agent_review,也不要用 review_pull 批准自己的 PR。
- 连续三次审查均退回发现后,下一次会就剩余问题询问人工,不应再以第四次修复硬碰。
- 可用 ask_agent_about_review(提供 head_sha 和 finding id)让审查者立即判定,回复以 VERDICT: withdrawn 或 VERDICT: stands 结尾。
- 关于未检查项的发现(如“从未在设备上运行”“没有测试覆盖”)在自己能处理时由自己关闭:运行或编写测试并在回复中说明。确实无法处理(如没有设备)才标 needs-human,并说明人工需运行什么。
台账
在 PR 上保留一条评论,列出每条评论及其状态,每轮编辑而非新发;以 <!-- mergepatrol-review-ledger --> 开头以便找回,跨轮保留每行并记录提出该评论的 head SHA。示例表格包含 Comment、Raised on、State、Note 四列。
禁止事项
- 不要在修复提交推送前或无理由回复时解决线程。
- 不要在人工答复前解决 needs-human 线程或 Mergepatrol 询问人工的线程。
- 不要在属于线程或台账的内容上另发新评论。
- 停止时不得留下未处理的评论;每条都应归于 fixed、dismissed 或 needs-human。
- 不要为可自行处理的事项打扰人工。
停止时向用户说明 PR 状态:已合并、因何被弹出,或每条 needs-human 评论需要谁做什么。
设置
.mergepatrol/mergepatrol.yml 可设置标签、批量大小、冲突解决器、校验命令、fix_ci 和 review。Mergepatrol 从默认分支读取该文件,因此修改在对应 PR 合并后生效。
限制与暂未提供
来自 fork 的 PR 仅按打标签时的状态合并:之后向它推送会使其离队,直到维护者重新添加标签;它不进入批量、不获得代理,冲突或检查失败即被弹出。仅当作者允许维护者编辑时,Mergepatrol 才能推送其变基。资料未说明具体定价、支持平台、安装步骤或性能指标。