release-runbook
Skill1 starsChanged 6 months agoMITView on GitHub
完整发版流水线(preflight → bump → release-check → PR → wait-ci → merge → tag → 监控 release.yml → publish draft)+ v0.1.0–v0.5.3 已踩坑的 known-failures playbook(matrix race / Windows MSI 字母版本号 / minisign 链 / lock 不同步 / Gatekeeper / Linux .deb 升级限制)。**用户说 `/release-runbook X.Y.Z` 或"发版 / release / 发个 patch / bump 到 X.Y.Z / 发 vX"时都用这个 skill**,不要自己散步骤跑——历史上每个 step 都有踩过的坑。
- Installs packages
- Commits and pushes
3 other projects use a version of this.
Adopted by
Most recently taken up by
- amplifthq/opentagtheir own version, first seen Oct 25, 2026
- amplifthq/openmeldtheir own version, first seen Oct 15, 2026
- elastic/elasticsearch-nettheir own version, first seen Aug 4, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- elastic/elasticsearch-net★ 3.7ksame name
- amplifthq/openmeld★ 1.4ksame name
- amplifthq/opentag★ 1.4ksame name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- crates/CLAUDE.mdCLAUDE.md
- openspec/CLAUDE.mdCLAUDE.md
- src-tauri/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- bug-huntSkill
- bump-versionSkill
- debug-firstSkill
- dep-updateSkill
- e2e-http-verifySkill
- insta-reviewSkill
- mark-tasks-doneSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-bulk-archive-changeSkill
- openspec-continue-changeSkill
- openspec-exploreSkill
- openspec-ff-changeSkill
- openspec-new-changeSkill
- openspec-onboardSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-verify-changeSkill
- perfSkill
- port-dashboardSkill
- preflightSkill
- refactorSkill
- ts-parity-checkSkill
- ts-ui-compareSkill
- wait-ciSkill
The file
Files
release-runbook
触发:
/release-runbook 0.5.4;或自然语言"发个 0.5.4 / 我们 release / bump 到 0.5.4 / 发个 patch / 出个新版本" 输出:步进式执行 + 每步状态报告 修改:三处版本号 + Cargo.lock + src-tauri/Cargo.lock;不动业务代码
一句话流程
preflight → 分支 → just release-bump X.Y.Z (bump 三处 + release-check + commit) →
push PR → /wait-ci → codex 二审(按豁免规则可跳)→ merge →
main 拉新 → tag vX.Y.Z → push tag → 监控 release.yml
(workflow 末尾 publish job 自动 verify 17 个 asset + un-draft,无需人工 publish)自动化点(v0.5.5 之后):
just release-bump X.Y.Z把"sed 三处 + CHANGELOG [Unreleased]→版本号 + release-check + git add + commit"做成一步(详scripts/release-bump.sh)release.yml末尾publishjob 自动校验 17 个必需 asset +gh release edit --draft=false,缺一即 fail 保留 draft 待人工介入
CHANGELOG 自动处理(v0.6.1 之后):
release-bump.sh在 bump 版本号同时自动将 CHANGELOG.md 的## [Unreleased]转为## [X.Y.Z] — YYYY-MM-DD+ 重建空[Unreleased]段 + 更新底部 compare 链接- Agent / 用户只需在 bump 前把本次改动写入
## [Unreleased]段(或确认已写好),不再需要手动改版本号/日期/链接
Agent / 人工只在 CI 红 / workflow build job 失败 / verify-asset 缺件 三种异常时介入。
何时用 release-engineer subagent vs 本 skill
- 本 skill(手把手):日常 patch(0.x.y bump、单 hotfix);要看清每一步、需要在某步停下沟通。
release-engineersubagent(Agent({ subagent_type: "release-engineer", ... })):大版本发版懒得手把手,subagent 在隔离 context 里自治推进,遇 known-failure 自动套 playbook fix,只在 playbook 不命中时回主对话升级。
两者共享同一 playbook(F1-F7);subagent 是把本 skill 跑到底的自动化版本。
何时用 bg dispatch
- 不用:发版本身是主线流程,需要随时看 CI 红绿决策——不要用
claude --bg。 - 例外:如果发版触发的 CI 期间你想并行干另一件不相关的事,那件事可以走 bg dispatch(参考
.claude/rules/parallelism-modes.md)。发版自身留主线。
已知失败 playbook(按历史出现频次排序)
逐项遇到时直接套用 fix——这都是 v0.1.0–v0.5.3 期间真实踩过的坑。
F1. release.yml matrix race(v0.4.2 案例)
症状:tag push 后产生 4 个 draft release,每个只含一个平台的 asset,无法 publish。
根因:4 个 matrix job 各自跑 tauri-action 并 releaseDraft: true → 各自调 createRelease → race。
修法:workflow 必须是 create-release 前置 job 产出 releaseId,build matrix 通过 with: releaseId: ${{ needs.create-release.outputs.id }} 复用。tauri-action 在给定 releaseId 时只上传 + merge latest.json,不再调 createRelease。检查 .github/workflows/release.yml 是否已是这种结构(CLAUDE.md "发布与分支策略"段已记,但 fork / rebase 后可能丢失)。
F2. Windows MSI version 含字母(CLAUDE.md 已记,仍易踩)
症状:Windows runner 报 pre-release identifier must be numeric-only。
修法:版本号 SHALL 是 X.Y.Z 纯数字(含 hotfix 0.3.1),不用 X.Y.Z-rc.1 / X.Y.Z-beta。演练应用内更新走真实 hotfix release,不走 rc。
F3. macos runner 不可用 / apt 冲突
症状(macos):macos-13 runner 被 GitHub 下线,job fail "no runner available"。
修法:升级到 macos-14(arm64);若历史 build 依赖 x86_64 ldd 等,改 macos-13-large 或 macos-latest-large。
症状(linux apt):E: Unable to locate package <X> 或 dpkg: error processing archive。
修法:在 apt-get install 前加 apt-get update;冲突包加 apt-get -y purge <pkg> 清掉再装。
F4. minisign 签名密钥配置(CLAUDE.md 已记)
症状:release bundle 不签名 / 应用内升级签名校验失败。
前置检查链(任一缺失即重新配置):
tauri.conf.json::bundle.createUpdaterArtifacts: truetauri.conf.json::plugins.updater.{endpoints,pubkey}已填capabilities/default.json::permissions含updater:default+process:defaultCargo.toml含tauri-plugin-updater+tauri-plugin-processlib.rs注册两个 pluginrelease.ymlenv 注入TAURI_SIGNING_PRIVATE_KEY+TAURI_SIGNING_PRIVATE_KEY_PASSWORD(GitHub Actions secret)
最大坑:私钥不可换。pubkey 已 commit 入库,老用户客户端只信旧公钥。
F5. Cargo.lock 与 manifest 不一致
症状:release PR 上 CI 报 lock file out of date。
根因:just release-check 跑会改 Cargo.lock + src-tauri/Cargo.lock,但 release commit 没 amend。
修法:bump 版本号后先跑 just release-check,再把改动的 lock 一起 amend / 重新 commit;不要先 commit bump 再跑 check。CLAUDE.md "发布与分支策略"段已固化。
F6. macOS Gatekeeper(用户安装报"无法验证")
症状:用户首次启动 .app 报 "无法打开,Apple 无法验证"。
根因:non-notarized;本仓暂不走 Apple 公证(成本 / 流程)。
修法(用户侧):右键 → 打开 → 跳过 Gatekeeper;或终端 xattr -cr /Applications/<app>.app。release notes 模板 SHALL 包含这两个步骤。
F7. Linux .deb 不支持应用内升级
症状:update.downloadAndInstall() 抛错。
根因:Tauri 限制——deb 无 in-place 升级机制。
修法:UI 层捕获该错误后弹"请到 GitHub 下载新版本"对话框(已实现);release notes 提示 Linux 用户手动下载。
工作步骤
Step 0:preflight
先调 preflight skill。要求:
- origin/main 已 fetch + 同步
- 当前分支非 main / master——切到
chore/release-X.Y.Z - 工作树干净
不满足就先解决。
Step 1:确认 CHANGELOG [Unreleased] 已写好
检查 CHANGELOG.md 的 ## [Unreleased] 段是否包含本次发版的改动条目。正常情况下每个 PR 合并时已随手追加(见 opsx-apply-cadence.md 第 8 步),此处只需确认没有遗漏。如果为空或明显缺条目:
git log --oneline <上个tag>..HEAD补写遗漏的用户可感知改动。release-bump.sh 只负责自动转格式(Unreleased → 版本号+日期+链接),不生成内容。
Step 2:本地 bump + commit(一行)
just release-bump X.Y.Zscripts/release-bump.sh 内部:
- 校验版本号格式(X.Y.Z 纯数字,拒 -rc/-beta,详 F2)
- 校验当前分支非 main / 工作树干净
- sed bump 三处版本号(
Cargo.tomlworkspace +src-tauri/Cargo.toml+src-tauri/tauri.conf.json) - CHANGELOG.md
[Unreleased]→[X.Y.Z] — 今日日期+ 重建空[Unreleased]+ 更新底部链接 - 跑
just release-check(同步刷新两份Cargo.lock,避免 F5) git add版本文件 + CHANGELOG +git commit -m "chore(release): X.Y.Z"
不 push、不 open PR——这两步保留 Agent / 人工拍板。
Step 3:push + 开 PR
git push -u origin chore/release-X.Y.Z
gh pr create --title "chore(release): X.Y.Z" --body "..."Step 4:等 CI 全绿(调用 wait-ci skill)
调用 wait-ci skill polling。任一 job 红:先看 F1–F7 是否命中已知 fix;命中则改 workflow 或 manifest 后 push fix commit;不命中则报告用户介入。
Step 4:codex 二审
按 .claude/rules/codex-usage.md 第 1 节判断——release commit 通常属于"显式豁免(bump version)"范畴,可跳过 codex 二审,但 PR 描述里写一句"未跑 codex(理由:纯 version bump)"留痕。如果这个 release 顺带改了 release.yml / Cargo manifest 不止版本号字段,那不算"纯 bump",仍要跑 codex。
Step 5:merge + tag
gh pr merge <pr> --squash --delete-branch
git checkout main && git pull
git tag vX.Y.Z
git push origin vX.Y.ZStep 6:监控 release.yml(自动 verify + publish)
gh run list --workflow=release.yml --limit 3
gh run watch <run-id> --exit-status --interval 30调用方式:Bash 工具 run_in_background: true + timeout: 3600000(1 h 上限)。release.yml 跨平台矩阵 + bundle 通常 20-30 min,远超 Bash 工具同步 10 min 上限;run_in_background 让 harness 在 gh run watch 退出时自动 task-notification 触发,避免 Bash timeout 误判失败。退出码:0 全绿、非 0 有 job 失败。不要主动 tail 输出 / ScheduleWakeup poll——bg 模式下 harness 已经在等 exit 信号,主动看是浪费 token。
workflow 结构:create-release → build (matrix×4) → publish(verify 17 个必需 asset + un-draft)。conclusion=success 即发版完成。
- 任一 build job 红:套 F1–F4 fix(matrix race / Windows MSI 字母版本号 / runner / minisign)
publishjob 红:通常是某平台 asset 缺失——gh release view vX.Y.Z --json assets -q '.assets[].name'对比 workflowREQUIRED列表定位;常见是 build 跑了但 tauri-action 没上传成功,re-run failed jobs 即可- 全绿 → release 已自动 publish,不需要人工
gh release edit --draft=false
仅当 workflow 内 publish job 缺失(fork / 老版本)时才回退到手工:
gh release edit vX.Y.Z --draft=false不要做
- 不要在 main 上 bump(一定走 PR)
- 不要在 release commit 之后再跑
just release-check——lock 一定会和 manifest 脱节(F5) - 不要尝试 rotate minisign 私钥(F4 最大坑)
- 不要给 tag 名加 rc / beta(F2)
- 不要在发版本身上用
claude --bg——发版需要随时看 CI 状态决策;如果你想并行干别的事,那件事走 bg,发版留主线
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

