release-please

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

release-please

Overview

概述

release-please automates versioning and releases by analyzing Conventional Commit messages:

Push conventional commits to your default branch
release-please creates/updates a Release PR with version bump and changelog
Merge the Release PR to trigger a GitHub Release
Publish step runs when a release is created (npm, PyPI, crates.io, etc.)

release-please handles version determination, changelog generation, and git tagging. You write good commit messages; it does the rest.

release-please通过分析Conventional Commit提交信息，实现版本管理和发布流程自动化：

推送符合Conventional Commits规范的提交到默认分支
release-please会创建/更新发布PR，包含版本升级和变更日志内容
合并发布PR即可触发GitHub Release生成
发布步骤会在Release创建时自动执行（支持npm、PyPI、crates.io等平台）

release-please会自动处理版本判定、变更日志生成和git打标签操作，你只需要编写规范的提交信息，其余工作都由它完成。

Commit Message Assistance

提交信息协助

When a user asks for help writing a commit message (not setting up a pipeline):

Ask what changed — "What did you change and why?" (skip if already described)
Suggest the type — Pick from the type table below, explain why that type fits
Draft the message — Write the full commit message (header + body if needed + footers)
Confirm — Present it for the user to approve or adjust

If the change is breaking, always include a

BREAKING CHANGE:

footer explaining migration impact.

当用户需要协助编写提交信息（而非设置流水线）时：

询问变更内容——「你修改了什么内容，修改原因是什么？」（如果用户已经说明可跳过本步）
建议提交类型——从下表中选择合适的类型，解释选择该类型的原因
草拟提交信息——编写完整的提交信息（标题+可选正文+可选页脚）
确认内容——将草拟的内容提交给用户确认或调整

如果变更属于破坏性更新，必须添加

BREAKING CHANGE:

页脚说明迁移影响。

Pipeline Setup Flow

流水线设置流程

When a user wants to set up release-please, follow this interactive protocol.

.github/workflows/release.yml

(or similar) already exists, read it first, compare against the templates in

references/workflow-templates.md

, and suggest specific improvements rather than replacing it wholesale. Common improvement opportunities: missing concurrency groups, publish not gated on

release_created

, missing idempotent publish check, overly broad permissions.

当用户需要设置release-please时，遵循以下交互流程。

如果仓库中已存在

.github/workflows/release.yml

（或类似文件），请先读取该文件，与

references/workflow-templates.md

中的模板对比，建议针对性的优化点而非直接完全替换。常见的优化点包括：缺失并发组配置、发布步骤未通过

release_created

条件控制、缺失幂等发布校验、权限范围过大。

Step 1: Detect Project Type

步骤1：检测项目类型

Scan the repository for package manifests:

File	Release Type
`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`

If multiple manifests exist at the root, ask which is primary. If none found, use

simple

扫描仓库中的包配置文件判定项目类型：

文件	发布类型
`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

类型。

Step 2: Ask Configuration Questions

步骤2：询问配置相关问题

Ask these questions (skip any already answered or obvious from context):

Is this a monorepo? (multiple packages in subdirectories)
What is the default branch? (default:
```
main
```
)
Do you need pre-release support? (manual alpha/beta/rc releases)
Where do you publish? (npm, GitHub Packages, PyPI, Maven Central, crates.io, Docker, none)
What is the current version? (check package manifest, default:
```
0.0.0
```
)

询问以下问题（如果用户已经回答或可从上下文推断可跳过）：

这是一个monorepo吗？（子目录下存在多个包）
默认分支名称是什么？（默认值：
```
main
```
）
需要预发布支持吗？（手动的alpha/beta/rc版本发布）
你需要发布到哪些平台？（npm、GitHub Packages、PyPI、Maven Central、crates.io、Docker、无需发布）
当前版本号是多少？（从包配置文件中读取，默认值：
```
0.0.0
```
）

Step 3: Generate Files

步骤3：生成配置文件

Create three files based on the answers:

根据上述回答生成三个文件：

release-please-config.json

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": []
    }
  }
}

Adjust

release-type

based on detected project type. For monorepos, add multiple entries under

packages

with

component

names.

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

json

{
  ".": "1.0.0"
}

Set to the current released version. Use

"0.0.0"

for new projects.

json

{
  ".": "1.0.0"
}

设置为当前已发布的版本号，新项目使用

"0.0.0"

。

.github/workflows/release.yml

For Node.js → npm public registry (most common), use this base template:

yaml

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 }}

For other ecosystems, see

references/workflow-templates.md

for complete templates including:

Node.js → GitHub Packages (with idempotent publish check)
Python → PyPI (trusted publishers)
Java → Maven Central
Go (tags only, optional GoReleaser)
Rust → crates.io
Docker (build + push with semver tags)
Monorepo (per-package publish jobs)
Pre-release pattern (workflow_dispatch with version resolution)

Always customize:

Replace
```
main
```
with the actual default branch if different
Adjust Node version, Python version, Java version, etc.
Add registry-specific secrets configuration
If pre-release support is needed, use the pre-release template from
```
references/workflow-templates.md
```

对于Node.js → npm公共仓库（最常见场景），使用以下基础模板：

yaml

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
```
请替换为实际分支名
调整Node版本、Python版本、Java版本等配置
添加对应仓库的密钥配置
如果需要预发布支持，使用
```
references/workflow-templates.md
```
中的预发布模板

Configuration Quick Reference

配置快速参考

Option	Default	Purpose
`release-type`	—	Package ecosystem (required)
`bump-minor-pre-major`	`false`	Treat `feat` as patch when < 1.0.0
`changelog-path`	`CHANGELOG.md`	Where to write the changelog
`include-v-in-tag`	`true`	Tag as `v1.2.3` vs `1.2.3`
`separate-pull-requests`	`false`	One PR per package (monorepo)
`draft`	`false`	Create release PRs as drafts
`extra-files`	`[]`	Additional files with version strings to update
`changelog-sections`	(defaults)	Customize which types appear in changelog

选项	默认值	用途
`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`	（monorepo场景）每个包单独生成PR
`draft`	`false`	将发布PR创建为草稿状态
`extra-files`	`[]`	需要同步更新版本号的其他文件
`changelog-sections`	（默认值）	自定义变更日志中展示的提交类型

Monorepo Quick Setup

Monorepo快速配置

json

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

json

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

Use component names as commit scopes:

feat(core): add streaming support

For full configuration options, see

references/config-options.md

json

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

json

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

提交信息中使用component名称作为scope：

feat(core): add streaming support

完整配置选项可查看

references/config-options.md

。

Commit Message Guide

提交信息指南

release-please reads commit messages to determine version bumps and generate changelogs. Every commit to the default branch must follow Conventional Commits.

release-please通过读取提交信息判定版本升级规则并生成变更日志，所有推送到默认分支的提交都必须遵循Conventional Commits规范。

Format

格式

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

[optional body]

[optional footer(s)]

Use imperative present tense: "add" not "added"
Do not capitalize the first letter of the description
Do not end with a period

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

[可选正文]

[可选页脚]

使用祈使句现在时：用「add」而非「added」
描述首字母不要大写
描述末尾不要加句号

Type → Version Bump

类型对应版本升级规则

Type	Bump	Triggers Release?
`feat`	Minor	Yes
`fix`	Patch	Yes
`deps`	Patch	Yes
`refactor`	—	No
`perf`	—	No
`test`	—	No
`docs`	—	No
`style`	—	No
`chore`	—	No
`build`	—	No
`ci`	—	No

Breaking changes (any type with

BREAKING CHANGE:

footer) → Major bump.

类型	升级版本	是否触发发布？
`feat`	次版本	是
`fix`	补丁版本	是
`deps`	补丁版本	是
`refactor`	—	否
`perf`	—	否
`test`	—	否
`docs`	—	否
`style`	—	否
`chore`	—	否
`build`	—	否
`ci`	—	否

破坏性变更（任意类型后加

或添加

BREAKING CHANGE:

页脚）→ 主版本升级。

Breaking Change Examples

破坏性变更示例

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.

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.

Special Footers

特殊页脚

Footer	Purpose
`BREAKING CHANGE: <desc>`	Triggers major version bump
`Release-As: x.x.x`	Force a specific version number

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

Quick Examples

快速示例

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

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

No AI Co-Author Trailers

禁止添加AI共同作者页脚

NEVER add
Co-Authored-By
trailers for AI agents in commit messages. These pollute changelogs and git history.

For the complete commit conventions reference with 15+ examples, scopes guide, and anti-patterns, see

references/commit-conventions.md

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

完整的提交规范参考（含15+示例、scope指南和反模式）可查看

references/commit-conventions.md

。

Best Practices

最佳实践

Squash Merges

压缩合并

Configure your repository to use squash merges for feature branches. This ensures each PR produces a single conventional commit, keeping the changelog clean. Set the squash commit message to use the PR title (which should be a conventional commit message).

配置仓库使用**squash merge（压缩合并）**合并功能分支，确保每个PR对应一条Conventional Commit提交，保持变更日志整洁。设置压缩合并的提交信息使用PR标题（PR标题应为符合规范的提交信息）。

Permissions

权限配置

The GitHub Action needs

contents: write

and

pull-requests: write

at minimum. Add

packages: write

id-token: write

for publish steps as needed. Use the principle of least privilege — grant permissions per-job, not at workflow level.

GitHub Action最少需要

contents: write

和

pull-requests: write

权限，发布步骤按需添加

packages: write

或

id-token: write

权限。遵循最小权限原则——按任务授予权限，不要在工作流全局配置权限。

Concurrency

并发配置

Always set

cancel-in-progress: false

for release workflows. Canceling a release mid-way can leave partial state (tags without releases, PRs in inconsistent state).

发布工作流始终设置

cancel-in-progress: false

，中途取消发布可能会产生部分状态（仅生成标签未生成Release、PR状态不一致）。

Publish Gating

发布条件控制

Never publish in the release-please job itself. Use a separate

publish

job gated on

release_created == 'true'

. This separates concerns and makes retries easier.

不要在release-please任务中直接执行发布操作，使用独立的

publish

任务，通过

release_created == 'true'

条件控制执行，实现职责分离，也便于重试。

Idempotent Publish

幂等发布

Check if the version already exists in the registry before publishing. This prevents failures on workflow re-runs:

yaml

- 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

发布前先校验版本是否已存在于仓库中，避免工作流重跑时失败：

yaml

- 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

Bootstrapping Existing Projects

已有项目接入

When adding release-please to a project with existing releases:

Set
```
.release-please-manifest.json
```
to your current version
Merge the setup PR with a
```
chore:
```
commit
release-please will create the next release PR based on subsequent commits
Alternatively, use
```
Release-As: x.x.x
```
footer to force a starting version

给已有发布历史的项目添加release-please时：

将
```
.release-please-manifest.json
```
中的版本设置为当前最新版本
使用
```
chore:
```
类型的提交合并配置PR
release-please会基于后续的提交生成下一个发布PR
也可以使用
```
Release-As: x.x.x
```
页脚强制指定初始版本

Troubleshooting

故障排查

No Release PR Created

未生成发布PR

Ensure commits since the last release include at least one releasable type (
```
feat
```
,
```
fix
```
,
```
deps
```
)
Check that commits are on the correct branch (must match workflow trigger)
Verify
```
release-please-config.json
```
and manifest exist and are valid JSON
Check Actions logs for permission errors

确保上一次发布以来的提交中至少包含一个可触发发布的类型（
```
feat
```
、
```
fix
```
、
```
deps
```
）
检查提交是否推送到了正确的分支（必须与工作流触发分支匹配）
确认
```
release-please-config.json
```
和manifest文件存在且是合法JSON
查看Actions日志排查权限错误

Wrong Version Bump

版本升级不符合预期

Review commit messages —
```
chore:
```
won't trigger a release,
```
feat:
```
triggers minor
Check for
```
BREAKING CHANGE:
```
footers that may trigger an unexpected major bump
Use
```
Release-As: x.x.x
```
footer to override if needed

检查提交信息——
```
chore:
```
类型不会触发发布，
```
feat:
```
类型触发次版本升级
检查是否存在
```
BREAKING CHANGE:
```
页脚导致意外的主版本升级
必要时使用
```
Release-As: x.x.x
```
页脚强制指定版本

Pre-Release Flow

预发布流程问题

Pre-releases use
```
workflow_dispatch
```
, not automatic push triggers
The pre-release identifier is appended to the current version:
```
1.2.3-alpha.1
```
Use the
```
next
```
npm tag (or equivalent) for pre-releases,
```
latest
```
for stable
See the pre-release template in
```
references/workflow-templates.md
```

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

Token / Permission Issues

令牌/权限问题

Default
```
GITHUB_TOKEN
```
works for release-please PRs and releases
Publishing to external registries requires dedicated secrets (
```
NPM_TOKEN
```
, etc.)
GitHub Packages publishing uses
```
GITHUB_TOKEN
```
with
```
packages: write
```
permission
For PyPI, use trusted publishers instead of API tokens

默认的
```
GITHUB_TOKEN
```
足够支持release-please生成PR和Release
发布到外部仓库需要专用密钥（
```
NPM_TOKEN
```
等）
发布到GitHub Packages使用
```
GITHUB_TOKEN
```
并授予
```
packages: write
```
权限
PyPI发布推荐使用可信发布者而非API令牌

References

参考资料

Reference	Description
`references/commit-conventions.md`	Full Conventional Commits specification with examples and anti-patterns
`references/workflow-templates.md`	Complete workflow templates for 9 ecosystems
`references/config-options.md`	All configuration options, release types, and Action inputs/outputs
release-please GitHub	Official documentation
Conventional Commits	Specification

参考文件	说明
`references/commit-conventions.md`	完整Conventional Commits规范，含示例和反模式
`references/workflow-templates.md`	覆盖9种技术栈的完整工作流模板
`references/config-options.md`	全部配置选项、发布类型和Action输入输出说明
release-please GitHub	官方文档
Conventional Commits	规范官方文档