OpenClaw Nightly 发布自动化全解:Tideclaw Alpha 分支隔离、发布 CI 与主干预合(Forward-Port)实战
【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw
本篇指南以 OpenClaw 仓库中的 release-openclaw-nightly 技能文档 为骨架,完整拆解 OpenClaw(Tideclaw)夜间/alpha 版本发布自动化流水线:从隔离分支创建、既有修复复用、发布 CI 触发,到 npm 发布证明、前向移植回main与分支保留策略。读者读完可掌握一套可复制的"从不干净的main上安全产出可用的 nightly 构建,并在验证通过后将可复用修复回传主干"的完整工程实践,包括版本号推算规则、阻断门与建议门的区分、以及gh只读/写包装器的使用边界。
为什么 nightly 必须隔离发布
OpenClaw 的发布策略文档明确了四条核心纪律:
- Alpha/nightly 每 12 小时运行一次,或由人工触发;
- Beta 由人工从 Discord 触发,且只能基于已被证明可用的 alpha/release 分支;
- Stable/latest 永远需要明确的人工确认;
- 绝不在脏工作区或直接从
main发布。
其根本原因在于:main可能处于忙碌或故障状态,瞬时的 main 故障不应阻塞一个可用的 nightly。因此 alpha 工作必须隔离进行,且只有在 release 分支证明全绿后才发布。发布成功后,再把 release 分支上的修复提交前向移植回main,并证明 main 的 CI 恢复绿色。
这条策略与仓库中实际的发布 CI 约束完全一致。查看 openclaw-release-publish.yml 的输入校验可以发现:alpha 发布只允许从匹配的tideclaw/alpha/YYYY-MM-DD-HHMMZ分支触发(tideclaw_alpha_publish=true),普通发布则必须从受保护的轻量release-publish/<tooling-sha12>-<epoch>标签触发,从main直接发布会被硬性拒绝。
发布前的 Backport 审计(Audit Nightly Backports)
当 alpha、beta 或修复分支需要发现/复用超出其固定基线的 backport 时,必须在改动候选分支之前完成一次自包含的审计。直接从当前固定的origin/main开启 alpha 不会自动产生 backport 审计,需要注意这一点。
审计的核心步骤:
- 固定基线:钉住确切的 release 基线与源 main SHA,从上次已接受的审计游标开始(无游标则从 merge base 开始);
- 枚举:列出每一个非 patch-equivalent 的源提交,对账已授权的公开/私有公告;
- 记录:将边界、数量、过滤器、适用性结果、决策、排除项、依赖与阻塞项写入现有 alpha 状态文件;
- 分类而非看标题:标题只是信号,不是闸门。完整清点清单,逐个检查带安全/可靠性信号的产线 diff,并单独审阅执行、认证、沙箱、网络、持久化、投递、网关、配置、插件以及主要通道路径上的常规
fix、perf、doctor提交; - 机械尝试:对每个 diff 在分离的基线 worktree 上做 cherry-pick 尝试,记录结果是 clean、conflicted、empty/already-covered 还是 failed。clean patch 只是分诊证据,不等于自动 backport;
- 快照 maturity:stable 标签的 issue:在钉住的源 SHA 处快照携带
maturity:stable标签的 OpenClaw issue 并记录标签查询时间。每个标签 issue(无论开闭)只要其修复 PR/commit 落在扫描区间内,都要给出 commit-ledger 决策;每个开放的 P0/P1 标签 issue 都要有明确的 fixed / not-affected / maintainer-deferred / blocked 发布处置。标签仅作完整性与优先级信号,不能仅凭标签推断修复、backport 批准或发布阻塞; - 逐项深审:对每个提议项检查完整变更、基线行为、调用方、被调用方、兄弟代码、测试、依赖契约、安全影响与发布表面,把重叠或相互依赖的提交折叠成最小的最终修复;
- 排除与批准:功能、迁移、新配置或运行时需求、大规模重构,除非维护者明确批准否则一律排除。完整分类集必须先提交审批再改动候选;审批后把 provenance 保留在状态文件中,运行聚焦证明与发布校验,并只在规范分支/标签拥有精确的最终版本与 SHA 之后才派发 npm preflight。
Tideclaw 机器身份与分支形态
提交身份(Identity)
Tideclaw 在 release 分支与前向移植分支上应使用自己的机器身份提交,保证可审计性(提交明显是机器生成且由 CI 把关):
git config user.name "Tideclaw" git config user.email "tideclaw@openclaw.ai"同时避免直接推送受保护的main:前向移植走 PR/自动合并,除非仓库策略明确允许 bot 在绿灯后推送。只有人工提供了补丁或明确提交文本时才附带Co-authored-by。
分支与标签命名(Branch Shape)
| 要素 | 约定 |
|---|---|
| 分支前缀 | tideclaw/alpha/ |
| 分支名 | tideclaw/alpha/YYYY-MM-DD-HHMMZ |
| 基线 | 触发时的当前origin/mainSHA |
| 状态文件 | 从 Tideclaw 主机上的$release-private解析 |
| 发布标签 | vYYYY.M.PATCH-alpha.N |
| npm dist-tag | alpha |
版本号推算规则(关键):
PATCH是顺序的月度发布列车号(release-train number),绝不是日历日;- 根据 stable 与 beta 发布确定 alpha 列车,忽略仅 alpha 的 patch 号来选择下一个列车;
- 取当月最高 stable/beta patch 加一;同一列车内多次 nightly 只递增
alpha.N; - 若下一个 patch 上已有 beta,则 alpha 移到后续列车;
- 历史遗留的带虚高 patch 号的 alpha-only 标签不推进beta/stable 编号;
- 不要为新一轮运行复用旧 alpha 分支:即使重跑同一 base SHA,也要新建带时间戳的分支并记录原因。
启动一次 nightly(Start)
标准流程在 Tideclaw 主机 checkout(来自$release-private)中执行:
- 先 fetch:
git fetch origin main --tags --prune git switch main git merge --ff-only origin/main BASE_SHA="$(git rev-parse origin/main)" BRANCH="tideclaw/alpha/$(date -u +%Y-%m-%d-%H%MZ)" git switch -c "$BRANCH" "$BASE_SHA"改动前必读仓库发布文档/脚本:
- AGENTS.md
docs/下的发布文档(如 docs/ci/release-validation/full-release-validation.md)scripts/下的发布脚本.github/workflows/*release*
幂等检查:将
$BASE_SHA与上次成功的 alpha 状态及当前 git/npm/GitHub alpha 标签对比,若已发布则报告 skip 且不发布。
人工触发(等价于 alpha cron):
CRON_ID="<from release-private>" OPENCLAW_ALLOW_ROOT=1 openclaw cron run "$CRON_ID" --expect-final --timeout 21600000Discord 触发:Alpha 与 Beta
Discord Alpha Trigger
当维护者在#releases或#maintainers提及 Tideclaw 时,可立即运行 alpha。接受的指令形态:
@Tideclaw run alpha now @Tideclaw alpha release from main now @Tideclaw trigger alpha规则要点:
- 视同 alpha cron 的人工触发;
- 从当前
origin/main新建tideclaw/alpha/YYYY-MM-DD-HHMMZ分支; - 走正常 alpha 流程:复用既有修复 → 本地检查 → 在 alpha 分支修复 → 运行发布 CI → 绿灯后发布 alpha → 以 fixes-only PR 前向移植;
- 若有其他 alpha/beta/stable 发布运行中,报告活动分支/运行并停止;
#maintainers触发必须显式提及 Tideclaw,不响应未提及的发布闲聊;- 从
$release-private解析 Discord 角色/用户 id 与主机 hotfix 备注。
Discord Beta Trigger
Beta 只能由维护者显式指令触发,视为对 beta 的人工批准(不代表对 stable/latest 的批准)。接受的指令形态:
@Tideclaw beta release from vYYYY.M.PATCH-alpha.N @Tideclaw beta release from tideclaw/alpha/YYYY-MM-DD-HHMMZ @Tideclaw beta release from latest proven alpha规则要点:
- 必须包含
beta release字样和一个源 alpha 标签/分支,或latest proven alpha; - 源不明确时,在
#releases中问一个澄清问题并停止; - 先验证源 alpha:GitHub release、npm
alpha包、发布 CI、记录的状态文件、分支/标签 SHA; - 从已被证明的 alpha 源新建
tideclaw/beta/YYYY-MM-DD-HHMMZ分支,绝不从移动的main直接建; - 只复用/压缩已在 alpha 上验证过的稳定化修复,不引入无关的 alpha 发布机制;
- Beta 版本计算为
vYYYY.M.PATCH-beta.N,匹配 npm--tag beta;选列车时忽略 alpha-only patch 号; - 在 beta 分支上运行 beta 发布校验/preflight/完整发布 CI 并修复失败;
- Beta 绿灯后才发布,使用 GitHub Actions/OIDC,绝不在主机上直接 npm publish;
- 最终 Discord 总结必须包含:源 alpha、beta 标签/版本、分支、修复提交、workflow run IDs、npm/GitHub 证明、任何跳过/阻塞原因;
- beta 发布后按同样的 fixes-only PR 规则前向移植。
复用既有修复(Reuse Prior Fixes)
运行检查前,先挖掘近期 Tideclaw alpha 分支上已做过的修复:
- 从
$release-private的 Tideclaw 状态文件读取上次成功 alpha 分支与 fix commit SHAs; - 列出远端分支:
git for-each-ref refs/remotes/origin/tideclaw/alpha --format='%(refname:short) %(committerdate:iso-strict)'- 只考虑最近 3 天的 Tideclaw alpha 分支加上上次成功的 alpha 分支;
- 对每个候选分支,检查不在当前
origin/main中的提交:
git log --no-merges --reverse --format='%H%x09%s' origin/main..origin/tideclaw/alpha/YYYY-MM-DD-HHMMZ- 只 cherry-pick 仍能应用到新 alpha 分支的真实稳定化修复。若这是"发现"而非复用状态文件中已批准的修复,必须先过 nightly backport 审计;clean cherry-pick 或无害的标题都不是批准依据。优先采用状态文件中记录的
fixCommitShas; - 跳过版本号 bump、changelog release 条目、标签产物、生成的发布说明、纯状态文件提交、一次性调试插桩;
- cherry-pick 冲突时,先检查当前 main 是否已含等价修复;若没有则最小化解冲突并保持提交信息清晰;
- 在 alpha 状态与最终 Discord 总结中分开记录复用的 commit SHAs 与新建的 fix SHAs。
用git cherry、git range-diff和定向测试重跑避免与main上已有的修复重复。
修复循环(Repair Loop)
把 alpha 分支当作 release-candidate 的修复表面:
- 先跑窄范围本地检查:变更测试、release preflight、发布文档要求的类型/lint/build 门;
- 本地检查失败 → 在 alpha 分支上以最小提交修复;
- 每个连贯修复以 Tideclaw 身份提交;
- 每次修复后重跑失败的本地检查;
- 不要通过编辑基线、预期失败列表、ignore 文件或发布清单来掩盖失败(除非发布文档明确要求且 diff 有正当理由);
- 失败若为 flaky,重跑一次;仍红则视为真实失败;
- 修复若明显对 main 有用,保持小而可移植,alpha 稳定化期间避免大范围重构。
提交示例:
git add <files> git commit -m "fix: stabilize alpha release preflight" git push -u origin "$BRANCH"发布 CI(Release CI):从 preflight 到 publish wrapper
触发 Full Release Validation 与 npm preflight
本地证明通过后:
- 从既有 git 标签、npm 版本与 GitHub releases 计算下一个
vYYYY.M.PATCH-alpha.N(PATCH取自 stable/beta 列车,而非日期或最高 alpha-only patch;复用同一 alpha 列车并递增alpha.N,直到该 patch 出现 beta 后用下一 patch); - 让 alpha 分支的包版本与 release 元数据匹配该标签,提交并推送分支;
- 用 GitHub CLI 而非 browser/fetch 工具运行发布校验。在 Tideclaw 主机上,裸
gh是只读的 Codex 沙箱包装器;写命令(workflow run、run cancel、发布 dispatch)使用/usr/local/bin/gh-tideclaw-write:
GH="/usr/local/bin/gh-tideclaw-write" SHA="$(git rev-parse HEAD)" TAG="v$(node -p "require('./package.json').version")" BRANCH="$(git branch --show-current)" "$GH" workflow run full-release-validation.yml --repo openclaw/openclaw --ref "$BRANCH" \ -f ref="$BRANCH" \ -f expected_sha="$SHA" \ -f release_profile=beta \ -f rerun_group=all "$GH" workflow run openclaw-npm-release.yml --repo openclaw/openclaw --ref "$BRANCH" \ -f tag="$SHA" \ -f preflight_only=true \ -f npm_dist_tag=alpha这里release_profile=beta与 full-release-validation.yml 的输入定义一致:beta 档案保持最快的 OpenAI/core 发布关键通道,run_release_soak默认false(stable/full 强制开启)。rerun_group=all是 full-release-validation.yml 提供的验证组之一(还有ci、plugin-prerelease、install-smoke、cross-os、live-e2e、package、qa-parity、qa-live、npm-telegram、performance),而 openclaw-release-publish.yml 会硬性校验:npm 发布前 Full Release Validation 必须跑过rerun_group=all。
- 用
gh run list、gh run view、gh api观察确切的 workflow run IDs 与 head SHA。只读gh用于轮询没问题;只有变更 GitHub 的命令才用$GH。不要用 Codex browser/fetch 轮询 GitHub API——文档明确记录此前 Tideclaw 运行在 preflight 成功之后在此失败过; - Alpha 的阻断门是 Tideclaw 能直接修复或能证明包安全性的门:正常 CI、plugin prerelease、npm preflight、包准备、install smoke、tag/可达性、发布验证。建议门(advisory)包括:跨 OS、live channel、QA Lab、包验收、长时 Docker E2E、Telegram 包 E2E——这些在 Discord 中报告并继续,只要阻断门全绿:
- 若
rerun_group=all仅在 CI、plugin prerelease、npm preflight、包准备、install smoke 全绿后卡在建议通道上,可在同一 head 上派发聚焦的-f rerun_group=install-smokeFull Release Validation,用这次成功的聚焦运行作为发布证明,并把独立的 CI/plugin/full 建议 run IDs 写进 Discord 总结;
- 若
- 阻断门失败 → 在 alpha 分支修复、推送,只重跑失败或必需的发布 CI。若提交变化,丢弃旧的 preflight/full-validation run IDs并为新 head 重跑;
- 同一分支 head 上 full validation 与 npm preflight 全绿后,审阅 npm preflight 的
Plugin SDK API diff摘要:若报告有变更,下载plugin-sdk-api-release-diff-<npm-preflight-run-id>-<run-attempt>工件,检查变更的声明,将PLUGIN_SDK_API_ACKNOWLEDGEMENT设为其digest前 8 个字符;否则置为空字符串。然后从该确切提交创建并推送发布标签:
NPM_PREFLIGHT_RUN_ATTEMPT="$(gh api \ "repos/openclaw/openclaw/actions/runs/${NPM_PREFLIGHT_RUN_ID}" \ --jq .run_attempt)" plugin_sdk_diff_dir="$(mktemp -d)" gh run download "$NPM_PREFLIGHT_RUN_ID" --repo openclaw/openclaw \ --name "plugin-sdk-api-release-diff-${NPM_PREFLIGHT_RUN_ID}-${NPM_PREFLIGHT_RUN_ATTEMPT}" \ --dir "$plugin_sdk_diff_dir" jq '{digest, entrypointsAdded, entrypointsRemoved, exports}' \ "$plugin_sdk_diff_dir/plugin-sdk-api-release-diff.json" PLUGIN_SDK_API_ACKNOWLEDGEMENT="" # 审阅非空 diff 后,使用其打印的 digest: # PLUGIN_SDK_API_ACKNOWLEDGEMENT="$(jq -r '.digest[0:8]' \ # "$plugin_sdk_diff_dir/plugin-sdk-api-release-diff.json")" git tag -a "$TAG" "$SHA" -m "openclaw ${TAG#v}" git push origin "$TAG" rm -rf "$plugin_sdk_diff_dir"PLUGIN_SDK_API_ACKNOWLEDGEMENT正是 openclaw-release-publish.yml 定义的输入(8 字符 Plugin SDK API diff digest),发布器会用 scripts/plugin-sdk-api-release-evidence.mjs 等校验器对账 manifest 与不可变工件(参见 openclaw-release-publish.yml 的cmp一致性检查)。
- 从同一 alpha 分支派发发布 wrapper,使用同一 head SHA 上成功的 npm preflight run ID 与 full release validation run ID 及精确 attempt:
FULL_RELEASE_VALIDATION_RUN_ATTEMPT="$(gh api \ "repos/openclaw/openclaw/actions/runs/${FULL_RELEASE_VALIDATION_RUN_ID}" \ --jq .run_attempt)" "$GH" workflow run openclaw-release-publish.yml --repo openclaw/openclaw --ref "$BRANCH" \ -f tag="$TAG" \ -f preflight_run_id="$NPM_PREFLIGHT_RUN_ID" \ -f full_release_validation_run_id="$FULL_RELEASE_VALIDATION_RUN_ID" \ -f full_release_validation_run_attempt="$FULL_RELEASE_VALIDATION_RUN_ATTEMPT" \ -f plugin_sdk_api_acknowledgement="$PLUGIN_SDK_API_ACKNOWLEDGEMENT" \ -f npm_dist_tag=alpha \ -f plugin_publish_scope=all-publishable \ -f publish_openclaw_npm=true \ -f release_profile=beta \ -f wait_for_clawhub=false发布器 openclaw-release-publish.yml 会做一系列硬校验:tag 格式必须是vYYYY.M.PATCH(-alpha.N|-beta.N|...);alpha 标签必须配 npm dist-tagalpha(L176-L179);发布子任务要求父任务运行在受保护的release-publish/标签或匹配的 Tideclaw alpha 分支上(L289-L295);发布 tag 必须可达自main、release/*、extended-stable/*或匹配的 alpha 分支(L892-L926)。publish_openclaw_npm=true还要求plugin_publish_scope=all-publishable,保证每个可发布的官方插件随 OpenClaw 一起发布(L296-L299)。
- 观察发布 wrapper 及其子运行。若
openclaw-npm-release.yml卡在等待npm-release环境审批而 Tideclaw 无法批准,将其报告为唯一阻塞项,不得宣布发布完成; - 绝不在主机上直接 npm publish,一律走 GitHub Actions/OIDC。
关键区分:
openclaw-npm-release.yml带preflight_only=true时只准备工件,不会发布。一次成功的 alpha 必须包含后续的openclaw-release-publish.ymlwrapper、推送的 git tag、npmalphadist-tag 证明与 GitHub prerelease。
验证已发布的 Alpha(Verify Published Alpha)
直到以下全部为真,发布才不算完成:
- GitHub tag 存在;
- GitHub Release 存在且标记为prerelease;
- Release 正文链接 npm 版本页、registry tarball、integrity 与 CI/proof;
npm view openclaw@<version>显示确切版本、dist-tagalpha、tarball、integrity 与发布时间;- 安装/包 smoke 遵循仓库发布文档;
$release-private的 Tideclaw 状态文件记录了版本、tag、base SHA、分支、fix commit SHAs、workflow run IDs、npm integrity 与时间戳。
最终 Discord 总结(发在#releases)需包含:tag/version、base SHA、branch、fix commits、workflow run IDs、npm/GitHub proof、以及未发布时的 skipped/blocked 原因。使用 Discord 安全的 Markdown 链接(尖括号目标),绝不打印 secrets。
前向移植(Forward-Port):把修复回传 main
成功 alpha 之后,向main提一个 fixes-only PR:
- 从当前
origin/main创建/更新前向移植分支:
git fetch origin main --prune git switch -c "tideclaw/forward-port/$(date -u +%Y-%m-%d-%H%MZ)" origin/main- 只 cherry-pick真实修复(为了让 nightly/release 检查通过所必需的提交);
- 排除:alpha 版本 bump、changelog release 条目、发布说明、tag 产物、生成的发布资产、纯状态文件提交、以及唯一目的是发布 alpha 的提交;
- 若提交混合了真实修复与发布/版本变更,拆分它:只把修复 hunks 重放到前向移植分支的新提交中;
- 冲突按最小 main 兼容修复解决;
- 运行相关变更/本地门;
- 推送并开 PR,或使用仓库允许的 bot 合并路径;
- 等待必需 main CI 全绿;失败则在 forward-port 分支修复并重跑;
- 报告 PR/合并 SHA 及任何故意未前向移植的提交。
若前向移植前origin/main已独立红掉,记录无关的失败检查,并尽可能让 forward-port PR 在自身 head 上保持绿色。
分支保留策略(Branch Retention)
每次运行前后清理旧 alpha 分支:
- 列出
origin/tideclaw/alpha/*; - 保留时间戳在最近 3 天 UTC内的分支;
- 保留被活动 workflow run、开放 PR、release tag 或状态文件引用的分支;
- 只删除 Tideclaw 拥有的 alpha 分支:
git push origin --delete tideclaw/alpha/YYYY-MM-DD-HHMMZ绝不删除人工分支、beta 分支、stable 分支或未知前缀。
停止条件(Stop Conditions)
遇到以下情况必须停止并清晰报告:
- 发布文档/脚本在版本化或发布路径上不一致;
- 必需的 secrets/auth 不可用;
- GitHub Actions 无法派发或观察;
- 真实修复尝试后必需发布门仍红;
- 发布后 npm/GitHub 状态不一致;
- 前向移植在无更大产品决策的情况下无法转绿。
关键源码索引
- 技能文档本体:.agents/skills/release-openclaw-nightly/SKILL.md
- 发布 umbrella(rerun_group / release_profile / fail_fast 参数):.github/workflows/full-release-validation.yml
- npm preflight 与发布门(
preflight_only语义):.github/workflows/openclaw-npm-release.yml - 发布 wrapper(tag 校验、evidence 校验、alpha 分支约束):.github/workflows/openclaw-release-publish.yml
- 发布校验文档(Validation SHA + Tooling SHA 元组、
release-publish/标签机制):docs/ci/release-validation/full-release-validation.md - 发布 CI 技能(immutable 计划、Release Decision 校验、
pnpm frv恢复):.agents/skills/release-openclaw-ci/SKILL.md
【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考