release-please

release-please

概述

release-please 通过分析 Conventional Commit 消息，自动完成版本管理和发布：

1. 推送 Conventional Commit 到默认分支
2. release-please 创建/更新发布 PR，其中包含版本升级和更新日志
3. 合并发布 PR，触发 GitHub Release
4. 创建 Release 时运行发布步骤（npm、PyPI、crates.io 等）

release-please 负责确定版本、生成更新日志和创建 git 标签。你只需写好提交消息，其余工作交给它完成。

提交消息辅助

用户请求协助编写提交消息（而非搭建流水线）时：

1. 询问变更内容——“你改了什么？为什么要改？”（如果已经说明，则跳过）
2. 建议类型——从下方的类型表中选择，并解释为何适合该类型
3. 起草消息——编写完整的提交消息（标题 + 正文（如有需要）+ 页脚）
4. 确认——展示消息，请用户批准或修改

如果变更会造成不兼容，务必添加 BREAKING CHANGE: 页脚，说明迁移影响。

流水线搭建流程

用户希望搭建 release-please 时，请遵循此交互流程。

如果 .github/workflows/release.yml（或类似文件）已存在，请先阅读，并与 references/workflow-templates.md 中的模板进行比较，然后提出具体改进建议，而不是直接整体替换。常见的改进机会包括：缺少并发组、未通过 release_created 控制发布步骤、缺少幂等发布检查、权限范围过宽。

步骤 1：检测项目类型

扫描仓库中的包清单文件：

文件	发布类型
package.json	node
pyproject.toml / setup.py	python
pom.xml	java
go.mod	go
Cargo.toml	rust
*.gemspec	ruby
composer.json	php
pubspec.yaml	dart
mix.exs	elixir
Chart.yaml	helm

如果根目录下存在多个清单文件，请询问哪个是主要项目。如果未找到，则使用 simple。

步骤 2：询问配置问题

询问以下问题（已回答或根据上下文显而易见的问题可跳过）：

1. 这是一个 monorepo 吗？（多个子目录中的包）
2. 默认分支是什么？（默认值：main）
3. 是否需要预发布支持？（手动发布 alpha/beta/rc 版本）
4. 在哪里发布？（npm、GitHub Packages、PyPI、Maven Central、crates.io、Docker、不发布）
5. 当前版本是什么？（检查包清单，默认值：0.0.0）

步骤 3：生成文件

根据答案创建三个文件：

release-please-config.json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": false,
      "draft": false,
      "prerelease": false,
      "versioning": "default",
      "extra-files": []
    }
  }
}

根据检测到的项目类型调整 release-type。对于 monorepo，在 packages 下添加多个条目，并为其设置 component 名称。

.release-please-manifest.json

{
  ".": "1.0.0"
}

设置为当前已发布的版本。对于新项目，使用 "0.0.0"。

.github/workflows/release.yml

对于 Node.js → npm 公共注册表（最常见的情况），使用以下基础模板：

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
      version: ${{ steps.release.outputs.version }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release

  publish:
    needs: release-please
    if: needs.release-please.outputs.release_created == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

对于其他生态系统，请参阅 references/workflow-templates.md 中的完整模板，包括：

• Node.js → GitHub Packages（包含幂等发布检查）
• Python → PyPI（可信发布者）
• Java → Maven Central
• Go（仅标签，可选使用 GoReleaser）
• Rust → crates.io
• Docker（通过 semver 标签进行构建和推送）
• Monorepo（按包划分的发布任务）
• 预发布模式（通过 workflow_dispatch 解析版本）

务必进行自定义：

• 如果默认分支不是 main，请将 main 替换为实际的默认分支
• 调整 Node 版本、Python 版本、Java 版本等
• 添加注册表专属的密钥配置
• 如果需要预发布支持，请使用 references/workflow-templates.md 中的预发布模板

配置快速参考

选项	默认值	用途
release-type	—	软件包生态系统（必填）
bump-minor-pre-major	false	版本低于 1.0.0 时，将 feat 视为补丁版本更新
changelog-path	CHANGELOG.md	写入变更日志的位置
include-v-in-tag	true	标签格式为 v1.2.3 还是 1.2.3
separate-pull-requests	false	每个软件包单独创建一个 PR（单体仓库）
draft	false	将发布 PR 创建为草稿
extra-files	[]	需要更新版本字符串的其他文件
changelog-sections	（默认值）	自定义变更日志中显示的类型

单体仓库快速设置

// release-please-config.json
{
  "packages": {
    "packages/core": { "release-type": "node", "component": "core" },
    "packages/cli": { "release-type": "node", "component": "cli" }
  }
}

// .release-please-manifest.json
{ "packages/core": "0.0.0", "packages/cli": "0.0.0" }

将组件名称用作提交范围：feat(core): add streaming support

完整配置选项请参阅 references/config-options.md。

提交消息指南

release-please 会读取提交消息来确定版本更新幅度并生成变更日志。默认分支上的每次提交都必须遵循约定式提交。

格式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

• 使用祈使语气的一般现在时：“add”，而非“added”
• 描述的首字母不要大写
• 末尾不要加句号

类型 → 版本更新幅度

类型	更新幅度	是否触发发布？
feat	次版本	是
fix	补丁版本	是
deps	补丁版本	是
refactor	—	否
perf	—	否
test	—	否
docs	—	否
style	—	否
chore	—	否
build	—	否
ci	—	否

重大变更（任何带 ! 的类型，或包含 BREAKING CHANGE: 页脚）→ 主版本更新。

重大变更示例

feat(api)!: redesign authentication flow

BREAKING CHANGE: /auth/login now requires OAuth2 tokens instead of API keys.

refactor(database): migrate from MongoDB to PostgreSQL

BREAKING CHANGE: all database connection strings must be updated.

特殊页脚

页脚	用途
BREAKING CHANGE: <desc>	触发主版本更新
Release-As: x.x.x	强制指定版本号

快速示例

feat(booking): add search by date range endpoint
fix(auth): resolve token refresh race condition
deps: upgrade @nestjs/core to v11.0.0
test(scheduler): add unit tests for cron parser
chore: update .gitignore

不要添加 AI 共同作者页脚

提交消息中绝不要为 AI Agent 添加 Co-Authored-By 页脚。这会污染变更日志和 git 历史记录。

完整的提交规范参考（含 15 个以上示例）、范围指南和反模式，请参阅 references/commit-conventions.md。

最佳实践

Squash 合并

将仓库配置为对功能分支使用 Squash 合并。这可确保每个 PR 生成一条符合约定的提交，从而保持变更日志整洁。将 Squash 提交消息设置为使用 PR 标题（标题应符合约定式提交格式）。

权限

GitHub Action 至少需要 contents: write 和 pull-requests: write。根据需要，为发布步骤添加 packages: write 或 id-token: write。遵循最小权限原则——按作业授予权限，而不是在工作流级别授予。

并发

发布工作流中始终将 cancel-in-progress: false 设为 false。在中途取消发布可能导致状态不完整（存在标签但没有发布，或 PR 状态不一致）。

发布门控

不要在 release-please 作业本身中发布。应使用一个由 release_created == 'true' 控制的独立 publish 作业。这样可以分离关注点，也更便于重试。

幂等发布

发布前检查注册表中是否已存在该版本。这可以避免工作流重新运行时失败：

- name: Check if version exists
  id: check
  run: |
    PACKAGE_NAME=$(node -p "require('./package.json').name")
    VERSION=$(node -p "require('./package.json').version")
    if npm view "${PACKAGE_NAME}@${VERSION}" version 2>/dev/null; then
      echo "exists=true" >> "$GITHUB_OUTPUT"
    else
      echo "exists=false" >> "$GITHUB_OUTPUT"
    fi
- if: steps.check.outputs.exists == 'false'
  run: npm publish

为现有项目引导配置

为已有发布记录的项目添加 release-please 时：

1. 将 .release-please-manifest.json 设置为当前版本
2. 使用 chore: 提交合并设置 PR
3. release-please 将根据后续提交创建下一个发布 PR
4. 或者，使用 Release-As: x.x.x 页脚强制指定起始版本

故障排除

未创建发布 PR

• 确保自上次发布以来的提交中至少包含一种可触发发布的类型（feat、fix、deps）
• 检查提交是否位于正确的分支（必须与工作流触发器匹配）
• 确认 release-please-config.json 和清单文件存在且为有效 JSON
• 检查 Actions 日志中是否有权限错误

版本号递增错误

• 检查提交消息——chore: 不会触发发布，feat: 会触发次版本号递增
• 检查是否有可能触发意外主版本号递增的 BREAKING CHANGE: 页脚
• 如需覆盖，请使用 Release-As: x.x.x 页脚

预发布流程

• 预发布使用 workflow_dispatch，而非自动推送触发器
• 预发布标识符会追加到当前版本号后：1.2.3-alpha.1
• 预发布使用 next npm 标签（或等效标签），稳定版使用 latest
• 请参阅 references/workflow-templates.md 中的预发布模板

令牌／权限问题

• 默认的 GITHUB_TOKEN 可用于 release-please PR 和发布
• 发布到外部注册表需要专用密钥（如 NPM_TOKEN）
• 发布到 GitHub Packages 时，GITHUB_TOKEN 需要 packages: write 权限
• 对于 PyPI，请使用可信发布者，而非 API 令牌

参考资料

参考资料	描述
references/commit-conventions.md	完整的 Conventional Commits 规范，包含示例和反模式
references/workflow-templates.md	适用于 9 种生态系统的完整工作流模板
references/config-options.md	所有配置选项、发布类型以及 Action 输入／输出
release-please GitHub	官方文档
Conventional Commits	规范