pstack 合并安全机制：为什么 SHA 一过期就拒绝合并？

pstack 合并安全机制为什么 SHA 一过期就拒绝合并【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claudepstack 是一个把 Poteto 的严谨 Agent 工作流移植到 Claude Code、Codex、GitHub Copilot、Pi 等平台的技能栈。它的 Shipping发货工作流内置了一套合并安全机制PR 的 SHA 一旦发生任何变化合并请求就会被直接拒绝。这篇文章用通俗语言讲清楚——为什么一个 40 位十六进制字符串的变化值得让整条合并流水线停下来。一、为什么 SHA 过期就拒绝合并先理解一个核心事实SHA 是 PR 内容的指纹。每一次 commit 都会生成一个唯一的 SHA也叫 OID。只要 PR 里改了一个字节——哪怕只是注释——head 分支的 SHA 就会变。pstack 把这一点当作整个安全机制的地基审批、CI 通过、独立验证结论全部只对某一个具体 SHA负责而不是对某个分支上的某个提交负责。这就回答了你看到的现象如果验证完成之后有人又 push 了一个新 commit、或者 base 分支前进了旧 SHA 就过期了此时再执行合并就可能是把一个从未被验证过的版本放进主干。️ 所以 pstack 的策略是SHA 变了一切结论作废宁可拒绝合并也不合并一个未经验证的修订版本。官方文档 docs/reference.md 描述了各运行时的安装与配置而合并安全的完整规则写在 merge-safety.md。二、LandingRevision唯一确定合的是什么的五元组pstack 用一个叫LandingRevision的结构来锁定合并对象定义见 landing.ts字段含义仓库 PR 编号哪个 PRheadRefOidhead 分支的 SHA你的代码在哪一版baseRefName目标分支名合到哪里baseRefOid目标分支的 SHA目标在哪一版注意base 分支的 SHA 也在保护范围内。很多人只盯着 head但 base 前进同样会让验证失效——同样的 patch 落到不同的主干上冲突风险和行为都可能不同。比较逻辑很简单任何一项对不上整份记录就判定为changed见 sameLandingRevisionchanged→ 状态变了拒绝并停止not-open→ PR 已关闭停止still-pending→ 待合并机制仍在不能绕过unavailable→ 读不到状态绝不等于没有请求必须人工核实这条规则值得划重点缺失的字段和不受支持的 API永远不意味着请求不存在。宁可停下来对账也不能为了让检查通过而悄悄替换已保存的记录。三、合并时如何用服务层 head 条件把关pstack 在 Shipping 工作流 第 7 步要求合并必须带上服务强制的 head 条件而不是合并前最后看一眼gh pr merge pr --repo owner/repo --squash --match-head-commit verified-head三种等价写法任选其一但必须携带完全验证过的那个 SHAgh的--match-head-commitGraphQLmergePullRequest的expectedHeadOidREST 合并端点的sha参数为什么最后看一眼再合并不够因为看和合之间有时间差。在这个窗口里 PR 完全可能被改写。带上 head 条件后GitHub 会在执行合并的瞬间做原子校验SHA 对不上直接返回HTTP 409拒绝。最后那一下读取的竞态窗口被服务端替你关掉了。⚠️ 但要知道边界head 条件不能原子地保护 base 分支。所以对 base 的观察要在合并前后各做一次并协调 retarget 权限而不能宣称目标完全受保护。四、cancel-pending过期 SHA 的标准取消动作改写分支或改 base 之前必须先用ship-pr取消所有挂起的合并机制auto-merge 和 merge queue 算两套独立机制。它位于 watch-pr 脚本目录ship-pr inspect --repo $owner/$repo --pr $pr $record_file ship-pr cancel-pending --record $record_file流程是读出当前完整 LandingRevision → 保存记录 → 取消时重新读取现场 → 与保存记录逐项比对 → 只有比对一致才真正取消。这一步正是SHA 过期就拒绝的具体体现取消操作本身也校验修订版本防止你取消的其实是别人刚改过的 PR。只有kind: cancelled加退出码 0才允许后续的改写操作其余结果一律停止、对账。五、它不是嘴上说说真实仓库的拒绝测试pstack 有一支实弹验证脚本会在一次性私有仓库里完整演练这套机制绝不在生产 PR 上测试服务行为验证通过某个 head SHA然后向分支再 push 一个新 commitSHA 过期用旧 SHA 执行gh pr merge --match-head-commit→ 被拒绝 ✅直接调 REST 端点带旧sha→ 收到HTTP 409✅确认 PR 依然是OPEN没有被误合 ✅换新的正确 SHA 再合并 → 成功且 merge commit 确实进了目标分支 ✅对应的行为测试见 integrity.test.ts其中专门覆盖了两个刁钻场景head 变了即使之前的 CI 和检查全绿也要拒绝只是 base 被 retarget 了head 和检查都没变同样拒绝。配合 babysit 工作流 的未知状态绝不允许合并原则形成闭环状态不明时停止比合并更安全。六、快速上手pstack 的安全合并四步法 想在项目里获得这套保护记住这四步即可安装插件Claude Code 里执行/plugin marketplace add加/plugin install pstackpstack-claude其他运行时安装方式见 README用 babysit 把 PR 推到 merge-ready拿到带 SHA 的验证结论合并带 head 条件--match-head-commit verified-headSHA 一变立即失败改写前 cancel-pending任何 rebase、retarget 之前先取消挂起机制只认cancelled结果。写在最后SHA 过期就拒绝合并看起来严苛本质是把验证结论的可信边界钉死在一个不可变的指纹上。分支会漂移、CI 会重跑、审批会过期——但 SHA 不会服务端的 head 条件把最后时刻的竞态交给平台原子判定而 pstack 的 Shipping 检查清单 确保 Agent 不会偷懒跳过其中任何一环。对新手来说这套机制最大的价值是即使你交给 Agent 的指令很简单它合并进主干的代码也一定是经过验证的那一版。【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考