OpenClaw Nightly 发布自动化全解:Tideclaw Alpha 分支隔离、发布 CI 与主干预合(Forward-Port)实战
2026/9/13 1:37:19 网站建设 项目流程

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 审计,需要注意这一点。

审计的核心步骤:

  1. 固定基线:钉住确切的 release 基线与源 main SHA,从上次已接受的审计游标开始(无游标则从 merge base 开始);
  2. 枚举:列出每一个非 patch-equivalent 的源提交,对账已授权的公开/私有公告;
  3. 记录:将边界、数量、过滤器、适用性结果、决策、排除项、依赖与阻塞项写入现有 alpha 状态文件;
  4. 分类而非看标题:标题只是信号,不是闸门。完整清点清单,逐个检查带安全/可靠性信号的产线 diff,并单独审阅执行、认证、沙箱、网络、持久化、投递、网关、配置、插件以及主要通道路径上的常规fixperfdoctor提交;
  5. 机械尝试:对每个 diff 在分离的基线 worktree 上做 cherry-pick 尝试,记录结果是 clean、conflicted、empty/already-covered 还是 failed。clean patch 只是分诊证据,不等于自动 backport
  6. 快照 maturity:stable 标签的 issue:在钉住的源 SHA 处快照携带maturity:stable标签的 OpenClaw issue 并记录标签查询时间。每个标签 issue(无论开闭)只要其修复 PR/commit 落在扫描区间内,都要给出 commit-ledger 决策;每个开放的 P0/P1 标签 issue 都要有明确的 fixed / not-affected / maintainer-deferred / blocked 发布处置。标签仅作完整性与优先级信号,不能仅凭标签推断修复、backport 批准或发布阻塞;
  7. 逐项深审:对每个提议项检查完整变更、基线行为、调用方、被调用方、兄弟代码、测试、依赖契约、安全影响与发布表面,把重叠或相互依赖的提交折叠成最小的最终修复;
  8. 排除与批准:功能、迁移、新配置或运行时需求、大规模重构,除非维护者明确批准否则一律排除。完整分类集必须先提交审批再改动候选;审批后把 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-tagalpha

版本号推算规则(关键)

  • 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)中执行:

  1. 先 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"
  1. 改动前必读仓库发布文档/脚本

    • AGENTS.md
    • docs/下的发布文档(如 docs/ci/release-validation/full-release-validation.md)
    • scripts/下的发布脚本
    • .github/workflows/*release*
  2. 幂等检查:将$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 21600000

Discord 触发:Alpha 与 Beta

Discord Alpha Trigger

当维护者在#releases#maintainers提及 Tideclaw 时,可立即运行 alpha。接受的指令形态:

@Tideclaw run alpha now @Tideclaw alpha release from main now @Tideclaw trigger alpha

规则要点:

  1. 视同 alpha cron 的人工触发;
  2. 从当前origin/main新建tideclaw/alpha/YYYY-MM-DD-HHMMZ分支;
  3. 走正常 alpha 流程:复用既有修复 → 本地检查 → 在 alpha 分支修复 → 运行发布 CI → 绿灯后发布 alpha → 以 fixes-only PR 前向移植;
  4. 若有其他 alpha/beta/stable 发布运行中,报告活动分支/运行并停止;
  5. #maintainers触发必须显式提及 Tideclaw,不响应未提及的发布闲聊;
  6. $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

规则要点:

  1. 必须包含beta release字样和一个源 alpha 标签/分支,或latest proven alpha
  2. 源不明确时,在#releases中问一个澄清问题并停止;
  3. 先验证源 alpha:GitHub release、npmalpha包、发布 CI、记录的状态文件、分支/标签 SHA;
  4. 已被证明的 alpha 源新建tideclaw/beta/YYYY-MM-DD-HHMMZ分支,绝不从移动的main直接建
  5. 只复用/压缩已在 alpha 上验证过的稳定化修复,不引入无关的 alpha 发布机制;
  6. Beta 版本计算为vYYYY.M.PATCH-beta.N,匹配 npm--tag beta;选列车时忽略 alpha-only patch 号;
  7. 在 beta 分支上运行 beta 发布校验/preflight/完整发布 CI 并修复失败;
  8. Beta 绿灯后才发布,使用 GitHub Actions/OIDC,绝不在主机上直接 npm publish
  9. 最终 Discord 总结必须包含:源 alpha、beta 标签/版本、分支、修复提交、workflow run IDs、npm/GitHub 证明、任何跳过/阻塞原因;
  10. beta 发布后按同样的 fixes-only PR 规则前向移植。

复用既有修复(Reuse Prior Fixes)

运行检查前,先挖掘近期 Tideclaw alpha 分支上已做过的修复:

  1. $release-private的 Tideclaw 状态文件读取上次成功 alpha 分支与 fix commit SHAs;
  2. 列出远端分支:
git for-each-ref refs/remotes/origin/tideclaw/alpha --format='%(refname:short) %(committerdate:iso-strict)'
  1. 只考虑最近 3 天的 Tideclaw alpha 分支加上上次成功的 alpha 分支;
  2. 对每个候选分支,检查不在当前origin/main中的提交:
git log --no-merges --reverse --format='%H%x09%s' origin/main..origin/tideclaw/alpha/YYYY-MM-DD-HHMMZ
  1. 只 cherry-pick 仍能应用到新 alpha 分支的真实稳定化修复。若这是"发现"而非复用状态文件中已批准的修复,必须先过 nightly backport 审计;clean cherry-pick 或无害的标题都不是批准依据。优先采用状态文件中记录的fixCommitShas
  2. 跳过版本号 bump、changelog release 条目、标签产物、生成的发布说明、纯状态文件提交、一次性调试插桩;
  3. cherry-pick 冲突时,先检查当前 main 是否已含等价修复;若没有则最小化解冲突并保持提交信息清晰;
  4. 在 alpha 状态与最终 Discord 总结中分开记录复用的 commit SHAs 与新建的 fix SHAs。

git cherrygit range-diff和定向测试重跑避免与main上已有的修复重复。

修复循环(Repair Loop)

把 alpha 分支当作 release-candidate 的修复表面:

  1. 先跑窄范围本地检查:变更测试、release preflight、发布文档要求的类型/lint/build 门;
  2. 本地检查失败 → 在 alpha 分支上以最小提交修复;
  3. 每个连贯修复以 Tideclaw 身份提交;
  4. 每次修复后重跑失败的本地检查;
  5. 不要通过编辑基线、预期失败列表、ignore 文件或发布清单来掩盖失败(除非发布文档明确要求且 diff 有正当理由);
  6. 失败若为 flaky,重跑一次;仍红则视为真实失败;
  7. 修复若明显对 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

本地证明通过后:

  1. 从既有 git 标签、npm 版本与 GitHub releases 计算下一个vYYYY.M.PATCH-alpha.NPATCH取自 stable/beta 列车,而非日期或最高 alpha-only patch;复用同一 alpha 列车并递增alpha.N,直到该 patch 出现 beta 后用下一 patch);
  2. 让 alpha 分支的包版本与 release 元数据匹配该标签,提交并推送分支;
  3. 用 GitHub CLI 而非 browser/fetch 工具运行发布校验。在 Tideclaw 主机上,裸gh是只读的 Codex 沙箱包装器;写命令(workflow runrun 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 提供的验证组之一(还有ciplugin-prereleaseinstall-smokecross-oslive-e2epackageqa-parityqa-livenpm-telegramperformance),而 openclaw-release-publish.yml 会硬性校验:npm 发布前 Full Release Validation 必须跑过rerun_group=all

  1. gh run listgh run viewgh api观察确切的 workflow run IDs 与 head SHA。只读gh用于轮询没问题;只有变更 GitHub 的命令才用$GH。不要用 Codex browser/fetch 轮询 GitHub API——文档明确记录此前 Tideclaw 运行在 preflight 成功之后在此失败过;
  2. 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 总结;
  3. 阻断门失败 → 在 alpha 分支修复、推送,只重跑失败或必需的发布 CI。若提交变化,丢弃旧的 preflight/full-validation run IDs并为新 head 重跑;
  4. 同一分支 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一致性检查)。

  1. 从同一 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 必须可达自mainrelease/*extended-stable/*或匹配的 alpha 分支(L892-L926)。publish_openclaw_npm=true还要求plugin_publish_scope=all-publishable,保证每个可发布的官方插件随 OpenClaw 一起发布(L296-L299)。

  1. 观察发布 wrapper 及其子运行。若openclaw-npm-release.yml卡在等待npm-release环境审批而 Tideclaw 无法批准,将其报告为唯一阻塞项,不得宣布发布完成
  2. 绝不在主机上直接 npm publish,一律走 GitHub Actions/OIDC。

关键区分:openclaw-npm-release.ymlpreflight_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:

  1. 从当前origin/main创建/更新前向移植分支:
git fetch origin main --prune git switch -c "tideclaw/forward-port/$(date -u +%Y-%m-%d-%H%MZ)" origin/main
  1. 只 cherry-pick真实修复(为了让 nightly/release 检查通过所必需的提交);
  2. 排除:alpha 版本 bump、changelog release 条目、发布说明、tag 产物、生成的发布资产、纯状态文件提交、以及唯一目的是发布 alpha 的提交;
  3. 若提交混合了真实修复与发布/版本变更,拆分它:只把修复 hunks 重放到前向移植分支的新提交中;
  4. 冲突按最小 main 兼容修复解决;
  5. 运行相关变更/本地门;
  6. 推送并开 PR,或使用仓库允许的 bot 合并路径;
  7. 等待必需 main CI 全绿;失败则在 forward-port 分支修复并重跑;
  8. 报告 PR/合并 SHA 及任何故意未前向移植的提交。

若前向移植前origin/main已独立红掉,记录无关的失败检查,并尽可能让 forward-port PR 在自身 head 上保持绿色。

分支保留策略(Branch Retention)

每次运行前后清理旧 alpha 分支:

  1. 列出origin/tideclaw/alpha/*
  2. 保留时间戳在最近 3 天 UTC内的分支;
  3. 保留被活动 workflow run、开放 PR、release tag 或状态文件引用的分支;
  4. 只删除 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),仅供参考

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询