[!info] related notes

• 工具资源: release-please
• 前置: Conventional Commits
• 部署衔接: Watchtower 自动部署

release-please 自动版本管理

目标与前提

在目标项目中让 release-please 根据提交维护 Release PR，并在合并后创建对应 tag 与 GitHub Release。构建镜像、上传安装包和部署是额外步骤，需要独立配置与验证；这不是当前 Thought Forest 已启用的发布流水线声明。

先确定发布分支、包路径、release-type、已有版本基线和 token 策略。已有项目应从真实 tag 与版本文件核对初始版本，不能把示例版本直接当作当前版本。

配置与流程

以下是单个 Node 包的 manifest 模式示例，保存为 release-please-config.json：

{
  "include-v-in-tag": true,
  "packages": {
    ".": { "release-type": "node" }
  }
}

还需要 .release-please-manifest.json。例如真实上次版本是 1.2.3 时：

{ ".": "1.2.3" }

在目标发布分支的 push 工作流中调用 googleapis/release-please-action@v4，指定上述 config-file 和 manifest-file。manifest 模式不要再用 action 的 release-type 输入替代配置文件。完整工作流和权限示例见 上游配置。

规范提交合并到发布分支
  → action 运行并创建/更新 Release PR
  → 维护者审查版本、changelog 与文件变更
  → 合并 Release PR 后 action 再次运行
  → 创建对应 GitHub Release 与 tag

feat、fix、breaking change 的常见版本策略及 0.x 例外见 release-please。并非所有 docs: / chore: 都绝对不发布；显式版本覆盖等配置会改变判断。

Token 与后续构建

默认 GITHUB_TOKEN 在权限和仓库策略允许时可以创建 Release PR 与 Release。它产生的普通 push / PR / release 事件通常不会再触发其他 workflow，这是防止递归运行的机制；显式 workflow_dispatch 和 repository_dispatch 有例外。

因此，若依赖 Release PR 自动跑另一套 CI，或依赖新 tag 触发独立构建，需要选择适当的 GitHub App token、PAT，或调整工作流衔接。PAT 不是 release-please 本身的强制前提，且凭据还必须具有目标操作所需权限。

也可在同一工作流内读取 release step 的 release_created / tag_name 输出，条件执行构建与上传；monorepo 的组件输出名需按上游说明处理。不要无条件在每次 Release PR 更新时发布。

只有镜像已构建并推送、部署端配置匹配时，watchtower-auto-deploy 才可能接续处理镜像更新。GitHub Release 本身不会直接触发 Watchtower。

验证

• Release PR 的目标分支、包版本、changelog 与改动范围正确。
• 合并后 tag 指向预期发布提交，GitHub Release 内容一致。
• 若配置了后续构建，检查对应 run 和产物版本；没有运行时先区分事件抑制与权限失败。
• 若配置了部署，再核对实际运行版本，不以 Release 创建成功代替部署验证。

学习检查

• 为什么 GITHUB_TOKEN 能创建 Release，却可能不能触发 tag 构建工作流？
• 为什么现有项目不能直接照抄 manifest 的版本号？
• 创建 Release、构建产物与部署分别需要什么成功证据？

参考

• release-please-action
• Manifest releaser
• 从工作流触发工作流