release-please-standards

Release-Please 标准

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用替代方案……
你需要了解规范的 release-please 工作流、清单和配置文件结构	你想以交互式工作流端到端审查或设置 release-please——请使用 configure-release-please
你正在根据文档中的约定检查现有的 release-please 设置	你想在更改前自动检测仓库类型和现有配置——请使用 configure-release-please
其他技能需要引用标准的 release-please 配置	你正在配置单体仓库组件标签、每个软件包的 extra-files，或共享标签→组件标签迁移——请使用 git-plugin:release-please-configuration

版本：2025.1

用于自动化语义化版本控制和变更日志生成的标准 release-please 配置。

标准配置

GitHub Actions 工作流

文件：.github/workflows/release-please.yml

发布 PR 需要使用能够触发其他工作流的令牌。有两种方式； GitHub App 令牌为首选（laurigates 组织标准），MY_RELEASE_PLEASE_TOKEN PAT 作为旧版备用方案保留。

GitHub App 令牌（首选）——create-github-app-token 使用 RELEASE_PLEASE_APP_ID（变量）和 RELEASE_PLEASE_PRIVATE_KEY（密钥）生成令牌， gitops 会为标记了 release_please = true 的仓库配置这些凭据：

name: Release Please

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v3
        id: app-token
        with:
          app-id: ${{ vars.RELEASE_PLEASE_APP_ID }}
          private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ steps.app-token.outputs.token }}

PAT（旧版）——在仓库设置中配置 MY_RELEASE_PLEASE_TOKEN 密钥：

      - uses: googleapis/release-please-action@v5
        with:
          token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }}

配置文件

文件：release-please-config.json

{
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-sections": [
        {"type": "feat", "section": "Features"},
        {"type": "fix", "section": "Bug Fixes"},
        {"type": "perf", "section": "Performance"},
        {"type": "deps", "section": "Dependencies"},
        {"type": "docs", "section": "Documentation", "hidden": true},
        {"type": "chore", "section": "Miscellaneous", "hidden": true}
      ]
    }
  },
  "plugins": ["node-workspace"]
}

文件：.release-please-manifest.json

{
  ".": "0.0.0"
}

注意：版本 0.0.0 是占位符——release-please 会自动更新此版本。

项目类型差异

Node.js 前端/后端

• release-type：node
• 插件：node-workspace
• 更新内容：package.json 版本字段

Python 服务

• release-type：python
• 更新内容：pyproject.toml 版本字段、代码中的 __version__

基础设施（Helm）

• release-type：helm
• 更新内容：Chart.yaml 版本字段

多软件包仓库

单体仓库中的每个软件包都需要设置 component，并在根目录设置 include-component-in-tag: true，还需要为每个软件包设置 extra-files，并可选择使用 linked-versions 插件：

{
  "packages": {
    "packages/frontend": {"release-type": "node", "component": "frontend"},
    "packages/backend": {"release-type": "node", "component": "backend"}
  },
  "plugins": ["node-workspace"]
}

有关完整的单体仓库策略——组件标签、重复标签 / 多路径修复、每个软件包的 extra-files 路径规则、关联版本、添加软件包，以及共享标签→组件标签迁移——请参阅 git-plugin:release-please-configuration。

必需组件

最低要求

1. 工作流文件：.github/workflows/release-please.yml

   • 使用 googleapis/release-please-action@v5
   • 令牌：GitHub App 令牌（首选）或 MY_RELEASE_PLEASE_TOKEN 密钥
   • 在推送到 main 时触发

2. 配置文件：release-please-config.json

   • 使用适用于项目的有效 release-type
   • 定义 changelog-sections

3. 清单文件：.release-please-manifest.json

   • 列出所有软件包及其当前版本

令牌配置

该工作流使用专用的发布令牌（而非 GITHUB_TOKEN），原因如下：

• 允许发布 PR 触发其他工作流
• 启用发布 PR 的 CI 检查
• 保持适当的审计记录

接受以下两种令牌方式：

方式	配置	适用场景
GitHub App 令牌（首选）	actions/create-github-app-token → app-id: ${{ vars.RELEASE_PLEASE_APP_ID }}、private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}，并作为 token: ${{ steps.app-token.outputs.token }} 传入	laurigates 组织标准——gitops 会为标记了 release_please = true 的仓库配置凭据
PAT（旧版）	token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }}	尚未设置 GitHub App 的场景

已使用 App 令牌方式的工作流符合要求——不要要求其改用 MY_RELEASE_PLEASE_TOKEN。

合规性检查

状态级别

状态	条件
PASS	三个文件均存在且配置有效
WARN	文件均存在，但使用了已弃用的操作版本（低于 v5）
FAIL	缺少必需文件或配置无效

验证规则

1. 工作流验证：

   • 操作版本：v5（如果版本较旧则警告）
   • 令牌：必须使用密钥，不得硬编码
   • 触发条件：必须包含针对 main 的 push

2. 配置验证：

   • release-type：必须有效（node、python、helm、simple）
   • changelog-sections：必须包含 feat 和 fix

3. 清单验证：

   • 必须是有效的 JSON
   • 软件包必须与配置匹配

受保护文件

重要：Release-please 会自动管理这些文件：

• CHANGELOG.md - 切勿手动编辑
• package.json、pyproject.toml、Chart.yaml 中的版本字段
• .release-please-manifest.json - 仅在初始设置时编辑

请参阅 release-please-protection 技能以了解强制执行方式。

Conventional Commits

Release-please 要求使用 Conventional Commits 格式的提交消息：

前缀	发布类型	示例
feat:	次要版本	feat: add user authentication
fix:	补丁版本	fix: correct login timeout
feat!:	主要版本	feat!: redesign API
BREAKING CHANGE:	主要版本	在提交正文中

安装

1. 创建工作流文件
2. 创建配置文件
3. 创建清单文件
4. 提供发布令牌 — 首选方式：设置 RELEASE_PLEASE_APP_ID 变量和 RELEASE_PLEASE_PRIVATE_KEY 密钥（gitops 会为设置了 release_please = true 的仓库配置这些内容）；旧方式：将 MY_RELEASE_PLEASE_TOKEN 添加到 仓库密钥
5. 确保 pre-commit 配置了 conventional-pre-commit 钩子

故障排除

未创建发布 PR

• 检查 Conventional Commits 格式
• 确认工作流具有正确的权限
• 确保令牌具有写入权限

版本未更新

• 检查清单文件是否为有效的 JSON
• 确认 release-type 与项目匹配
• 检查 Actions 中的 release-please 日志

发布 PR 未触发 CI

• 令牌必须是专用的发布令牌（GitHub App 令牌或 PAT），不能是 GITHUB_TOKEN
• 确认工作流触发条件包含 pull_request