release-please

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Please

Practical guide for setting up and operating Release Please using

googleapis/release-please

and

googleapis/release-please-action

实用指南：使用

googleapis/release-please

和

googleapis/release-please-action

搭建并操作Release Please。

When to Use

适用场景

Use this skill when you need:

Automated version bumps + changelog from Conventional Commits
GitHub release PR automation on
```
main
```
/
```
master
```
Monorepo or multi-package release orchestration (manifest mode)
Migration from manual version/changelog/tag release workflows

Use single-package mode when one version stream exists. Use manifest mode when multiple packages/paths version independently.

当你有以下需求时，可使用本技能：

基于Conventional Commits实现自动版本升级和变更日志生成
在
```
main
```
/
```
master
```
分支上自动化GitHub发布PR
单体仓库或多包项目的发布编排（清单模式）
从手动版本/变更日志/标签发布工作流迁移至自动化方案

单包模式适用于仅有一条版本流的项目。清单模式适用于多包/多路径独立版本管理的项目。

Prerequisites

前置条件

1) Commit and branching hygiene

1) 提交与分支规范

Conventional Commits are required for accurate semver bumping and changelog sections.
Protected default branch recommended (
```
main
```
)
CI must run on release PRs and direct pushes to default branch

必须使用Conventional Commits，以确保准确的语义化版本升级和变更日志分区。
建议保护默认分支（
```
main
```
）
CI必须在发布PR和直接推送到默认分支时运行

2) Repository permissions and token strategy

2) 仓库权限与令牌策略

Choose one and stay consistent:

```
GITHUB_TOKEN
```
(simpler, default)
PAT / GitHub App token (when cross-repo, stricter org policy, or release-trigger chaining is needed)

Minimum permissions for workflow job:

```
contents: write
```
```
pull-requests: write
```
```
issues: write
```
(optional but useful for labeling/commenting behavior)

选择其中一种并保持一致：

```
GITHUB_TOKEN
```
（更简单，默认选项）
PAT / GitHub应用令牌（适用于跨仓库、严格组织策略或需要触发链式发布的场景）

工作流作业所需的最低权限：

```
contents: write
```
```
pull-requests: write
```
```
issues: write
```
（可选，但有助于标签/评论功能）

3) Required files (depending on mode)

3) 所需文件（依模式而定）

Single-package (minimal):

```
.github/workflows/release-please.yml
```

Manifest mode (monorepo / multiple packages):

```
.github/workflows/release-please.yml
```
```
release-please-config.json
```
```
.release-please-manifest.json
```

单包模式（最小配置）：

```
.github/workflows/release-please.yml
```

清单模式（单体仓库 / 多包项目）：

```
.github/workflows/release-please.yml
```
```
release-please-config.json
```
```
.release-please-manifest.json
```

Implementation Playbooks

实施指南

Playbook A — Action-based setup (single package)

指南A — 基于Action的单包搭建

Create

.github/workflows/release-please.yml

yaml

name: release-please

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

What happens:

On push to
```
main
```
, action evaluates commit history
Creates/updates a Release PR when a releasable change exists
After Release PR merge, creates tag + GitHub release

创建

.github/workflows/release-please.yml

：

yaml

"name": "release-please"

on:
  push:
    branches: [main]

permissions:
  "contents": "write"
  "pull-requests": "write"

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

执行流程：

当代码推送到
```
main
```
分支时，Action会评估提交历史
当存在可发布的变更时，创建或更新发布PR
发布PR合并后，自动创建标签和GitHub发布

Playbook B — Config-driven setup (manifest mode)

指南B — 基于配置的清单模式搭建

release-please-config.json

release-please-config.json

json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "node",
  "packages": {
    ".": {
      "release-type": "node"
    },
    "packages/pkg-a": {
      "release-type": "node"
    },
    "packages/pkg-b": {
      "release-type": "node"
    }
  }
}

json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "node",
  "packages": {
    ".": {
      "release-type": "node"
    },
    "packages/pkg-a": {
      "release-type": "node"
    },
    "packages/pkg-b": {
      "release-type": "node"
    }
  }
}

.release-please-manifest.json

.release-please-manifest.json

json

{
  ".": "0.1.0",
  "packages/pkg-a": "0.1.0",
  "packages/pkg-b": "0.1.0"
}

json

{
  ".": "0.1.0",
  "packages/pkg-a": "0.1.0",
  "packages/pkg-b": "0.1.0"
}

Workflow (manifest)

工作流（清单模式）

yaml

name: release-please

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          manifest-file: .release-please-manifest.json
          config-file: release-please-config.json

Notes:

Package keys must match real repo paths exactly
Manifest versions are the source of truth for next bumps

yaml

"name": "release-please"

on:
  push:
    branches: [main]

permissions:
  "contents": "write"
  "pull-requests": "write"

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          manifest-file: .release-please-manifest.json
          config-file: release-please-config.json

注意事项：

包的键名必须与仓库中的实际路径完全匹配
清单中的版本是下一次版本升级的基准版本

Playbook C — Migration from manual releases

指南C — 从手动发布迁移至自动化

Normalize commit style to Conventional Commits from now onward.
Add workflow (single or manifest mode).
Seed versions in
```
.release-please-manifest.json
```
to current released versions (manifest mode).
Merge first Release PR.
Stop manual tag/changelog edits on default branch.

从现在开始统一使用Conventional Commits提交规范。
添加工作流（单包或清单模式）。
在
```
.release-please-manifest.json
```
中填入当前已发布的版本（清单模式）。
合并第一个发布PR。
停止在默认分支上手动编辑标签和变更日志。

Operational Workflows

操作工作流

Bootstrap first automated release

首次自动化发布引导

Checklist:

Workflow merged to default branch
At least one releasable commit (
```
feat:
```
,
```
fix:
```
) exists after baseline
Token permissions validated
For manifest mode, config + manifest committed and valid paths

Expected result: first Release PR appears (

release-please--branches--main

style).

检查清单：

工作流已合并至默认分支
基准版本之后至少存在一个可发布的提交（
```
feat:
```
、
```
fix:
```
类型）
令牌权限已验证
清单模式下，配置文件和清单文件已提交且路径有效

预期结果：第一个发布PR将自动创建（命名格式类似

release-please--branches--main

）。

Ongoing release PR lifecycle

日常发布PR生命周期

Developers merge Conventional Commit PRs.
Release Please updates existing release PR (or opens a new one).
CI validates release PR.
Merge release PR when ready.
Action creates tag + GitHub Release.

开发者合并符合Conventional Commits规范的PR。
Release Please更新已有的发布PR（或创建新的PR）。
CI验证发布PR。
准备就绪后合并发布PR。
Action自动创建标签和GitHub发布。

Tag/release behavior

标签/发布行为

Tag/release happens after merge of release PR to tracked branch.
Changelog + version files are authored in the release PR.
Don’t hand-edit generated release PR content unless required by policy.

标签和发布在发布PR合并至跟踪分支后生成。
变更日志和版本文件由发布PR自动生成。
除非有政策要求，否则不要手动编辑生成的发布PR内容。

Dry-run/testing strategy

试运行/测试策略

Validate config/manifest paths via PR checks before enabling strict branch rules.
In test repos/branches, run with same workflow first.
For production repos, start with one package path, then expand manifest coverage.

在启用严格分支规则前，通过PR检查验证配置文件和清单文件的路径。
先在测试仓库/分支中运行相同的工作流。
对于生产仓库，先从单个包路径开始，再逐步扩展清单覆盖范围。

Troubleshooting

故障排查

No release PR created

未创建发布PR

Check:

No releasable commit types since last release (docs/chore only)
Workflow not firing on tracked branch
Token lacks
```
contents: write
```
/
```
pull-requests: write
```
Existing stale release PR already open

检查项：

自上次发布以来没有可发布的提交类型（仅docs/chore类型提交）
工作流未在跟踪分支上触发
令牌缺少
```
contents: write
```
/
```
pull-requests: write
```
权限
已存在未处理的过期发布PR

Wrong version bump

版本升级错误

Usually commit semantics mismatch:

```
fix:
```
=> patch
```
feat:
```
=> minor
breaking change footer /
```
!
```
=> major

Audit merged commit messages first; Release Please is usually doing exactly what commits say.

通常是因为提交语义不匹配：

```
fix:
```
=> 补丁版本（patch）
```
feat:
```
=> 次版本（minor）
包含breaking change脚注 /
```
!
```
=> 主版本（major）

首先审核已合并的提交信息；Release Please通常会严格按照提交信息执行操作。

Changelog missing/incorrect entries

变更日志条目缺失/错误

Confirm commits are Conventional Commit compliant
Check release type + package path mapping in config
Ensure squash merge titles are also Conventional Commit compatible

确认提交符合Conventional Commits规范
检查配置文件中的发布类型与包路径映射
确保合并时的压缩提交标题也符合Conventional Commits规范

Manifest sync issues (monorepo)

清单同步问题（单体仓库）

Symptoms: wrong package bumped or no bump.

Path key mismatch between
```
packages
```
config and actual directory
```
.release-please-manifest.json
```
has stale/missing package key
Package moved/renamed without updating both files

症状：错误的包被升级或未触发升级。

配置文件中
```
packages
```
的路径与实际目录不匹配
```
.release-please-manifest.json
```
中存在过期或缺失的包键
包被移动/重命名但未更新配置文件和清单文件

Token/permissions failures

令牌/权限失败

```
Resource not accessible by integration
```
=> wrong token scope/permissions
Org policy may block default
```
GITHUB_TOKEN
```
; use PAT/App token
Ensure workflow-level
```
permissions
```
block is explicitly set

```
Resource not accessible by integration
```
=> 令牌范围/权限不足
组织政策可能限制默认的
```
GITHUB_TOKEN
```
；请使用PAT/应用令牌
确保工作流级别的
```
permissions
```
块已明确设置

Best Practices and Guardrails

最佳实践与防护措施

Enforce Conventional Commit linting in CI
Keep release cadence predictable (e.g., weekly or on-demand but explicit)
Protect default branch and require CI on release PRs
Avoid manual tags/changelog edits on release-managed branches
Keep release PR small; don’t batch unrelated long-lived work
In monorepos, add packages incrementally and verify each path mapping
Document release ownership (who merges release PRs)

在CI中强制实施Conventional Commits规范校验
保持发布节奏可预测（例如每周固定时间或按需但明确触发）
保护默认分支并要求CI验证发布PR
避免在由Release Please管理的分支上手动编辑标签/变更日志
保持发布PR精简；不要批量合并无关的长期工作内容
在单体仓库中，逐步添加包并验证每个路径映射
明确发布负责人（谁负责合并发布PR）

Quick Verification Checklist

快速验证清单

References

参考资料

Primary upstream sources:

Core project:
```
googleapis/release-please
```
- https://github.com/googleapis/release-please
GitHub Action (current):
```
googleapis/release-please-action
```
- https://github.com/googleapis/release-please-action

Historical/migration context:

Archived old action:
```
google-github-actions/release-please-action
```
- https://github.com/google-github-actions/release-please-action

主要上游资源：

核心项目：
```
googleapis/release-please
```
- https://github.com/googleapis/release-please
GitHub Action（当前版本）：
```
googleapis/release-please-action
```
- https://github.com/googleapis/release-please-action

历史/迁移相关：

已归档的旧版Action：
```
google-github-actions/release-please-action
```
- https://github.com/google-github-actions/release-please-action