release-please-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release-Please Configuration

Release-Please 配置

Expert knowledge for configuring Google's release-please for automated releases.

本文提供配置Google的release-please以实现自动化发布的专业知识。

Core Files

核心文件

File	Purpose
`release-please-config.json`	Package configuration, changelog sections, extra-files
`.release-please-manifest.json`	Current versions for each package
`.github/workflows/release-please.yml`	GitHub Actions workflow

文件	用途
`release-please-config.json`	包配置、变更日志章节、额外文件设置
`.release-please-manifest.json`	跟踪每个包的当前版本
`.github/workflows/release-please.yml`	GitHub Actions 工作流

Monorepo Configuration

单体仓库配置

Critical Settings for Monorepos

单体仓库关键配置

json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "include-component-in-tag": true,
  "separate-pull-requests": true,
  "packages": {
    "package-a": {
      "component": "package-a",
      "release-type": "simple",
      "extra-files": ["package-a/version.json"]
    }
  }
}

Key Fields:

Field	Required	Purpose
`include-component-in-tag`	Yes (monorepo)	Creates `package-a-v1.0.0` tags instead of `v1.0.0`
`component`	Yes (monorepo)	Unique identifier for each package; must be set for every package
`separate-pull-requests`	Recommended	Creates per-package release PRs instead of combined

json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "include-component-in-tag": true,
  "separate-pull-requests": true,
  "packages": {
    "package-a": {
      "component": "package-a",
      "release-type": "simple",
      "extra-files": ["package-a/version.json"]
    }
  }
}

关键字段：

字段	是否必填	用途
`include-component-in-tag`	是（单体仓库）	创建 `package-a-v1.0.0` 格式的标签，而非 `v1.0.0`
`component`	是（单体仓库）	每个包的唯一标识符；必须为每个包设置
`separate-pull-requests`	推荐	为每个包单独创建发布PR，而非合并为一个

Common Failure: Duplicate Release Tags

常见问题：重复发布标签

Symptom: Workflow fails with

Duplicate release tag: v2.0.0

Cause: All packages try to create the same tag (e.g.,

v2.0.0

) because:

Missing
```
include-component-in-tag: true
```
at root level
Missing
```
component
```
field in each package

Fix:

json

{
  "include-component-in-tag": true,
  "packages": {
    "my-package": {
      "component": "my-package",  // Add this to every package
      ...
    }
  }
}

症状： 工作流失败，提示

Duplicate release tag: v2.0.0

原因： 所有包尝试创建相同的标签（如

v2.0.0

），因为：

根配置中缺少
```
include-component-in-tag: true
```
每个包的配置中缺少
```
component
```
字段

修复方案：

json

{
  "include-component-in-tag": true,
  "packages": {
    "my-package": {
      "component": "my-package",  // 为每个包添加此字段
      ...
    }
  }
}

Common Failure: Multiple Paths Warning

常见问题：多路径警告

Symptom:

Multiple paths for : package-a, package-b

Cause: Empty

component

field (the

with nothing after it indicates empty string)

Fix: Ensure every package has

"component": "package-name"

set

症状： 提示

Multiple paths for : package-a, package-b

原因：

component

字段为空（冒号后无内容表示空字符串）

修复方案： 确保每个包都设置了

"component": "package-name"

Release Types

发布类型

Type	Use Case	Version File
`simple`	Generic projects	`version.txt`
`node`	npm packages	`package.json`
`python`	Python (pyproject.toml)	`pyproject.toml`
`rust`	Rust crates	`Cargo.toml`
`go`	Go modules	`version.go` or similar

类型	使用场景	版本文件
`simple`	通用项目	`version.txt`
`node`	npm 包	`package.json`
`python`	Python 项目（pyproject.toml）	`pyproject.toml`
`rust`	Rust 包	`Cargo.toml`
`go`	Go 模块	`version.go` 或类似文件

Extra Files for Custom Version Locations

自定义版本位置的额外文件

For JSON files, you must use the object format with

type

path

, and

jsonpath

json

{
  "packages": {
    "my-plugin": {
      "release-type": "simple",
      "extra-files": [
        {"type": "json", "path": "my-plugin/.claude-plugin/plugin.json", "jsonpath": "$.version"}
      ]
    }
  }
}

Common Mistakes:

Using a simple string path for JSON files:

json

// WRONG - won't update the version field
"extra-files": [".claude-plugin/plugin.json"]

// CORRECT - uses JSON updater with jsonpath
"extra-files": [
  {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
]

Using absolute paths instead of package-relative paths:

json

// WRONG - path gets doubled (package-name/package-name/.claude-plugin/...)
"extra-files": [
  {"type": "json", "path": "my-plugin/.claude-plugin/plugin.json", "jsonpath": "$.version"}
]

// CORRECT - path is relative to the package directory
"extra-files": [
  {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
]

Key insight: For monorepo packages,

extra-files

paths are relative to the package directory, NOT the repo root. Release-please automatically prepends the package path.

File Type Formats:

File Type	Format
JSON	`{"type": "json", "path": "...", "jsonpath": "$.version"}`
YAML	`{"type": "yaml", "path": "...", "jsonpath": "$.version"}`
TOML	`{"type": "toml", "path": "...", "jsonpath": "$.version"}`
XML	`{"type": "xml", "path": "...", "xpath": "//version"}`
Plain text	`"path/to/version.txt"` (string is fine)

对于JSON文件，必须使用包含

type

、

path

和

jsonpath

的对象格式：

json

{
  "packages": {
    "my-plugin": {
      "release-type": "simple",
      "extra-files": [
        {"type": "json", "path": "my-plugin/.claude-plugin/plugin.json", "jsonpath": "$.version"}
      ]
    }
  }
}

常见错误：

为JSON文件使用简单字符串路径：

json

// 错误 - 无法更新版本字段
"extra-files": [".claude-plugin/plugin.json"]

// 正确 - 使用带jsonpath的JSON更新器
"extra-files": [
  {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
]

使用绝对路径而非包相对路径：

json

// 错误 - 路径会被重复（package-name/package-name/.claude-plugin/...）
"extra-files": [
  {"type": "json", "path": "my-plugin/.claude-plugin/plugin.json", "jsonpath": "$.version"}
]

// 正确 - 路径相对于包目录
"extra-files": [
  {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
]

关键提示： 对于单体仓库的包，

extra-files

的路径是相对于包目录的，而非仓库根目录。Release-please会自动添加包路径前缀。

文件类型格式：

文件类型	格式
JSON	`{"type": "json", "path": "...", "jsonpath": "$.version"}`
YAML	`{"type": "yaml", "path": "...", "jsonpath": "$.version"}`
TOML	`{"type": "toml", "path": "...", "jsonpath": "$.version"}`
XML	`{"type": "xml", "path": "...", "xpath": "//version"}`
纯文本	`"path/to/version.txt"` （字符串格式即可）

Changelog Configuration

变更日志配置

Standard Changelog Sections

标准变更日志章节

json

{
  "changelog-sections": [
    {"type": "feat", "section": "Features"},
    {"type": "fix", "section": "Bug Fixes"},
    {"type": "perf", "section": "Performance"},
    {"type": "refactor", "section": "Code Refactoring"},
    {"type": "docs", "section": "Documentation"}
  ]
}

json

{
  "changelog-sections": [
    {"type": "feat", "section": "Features"},
    {"type": "fix", "section": "Bug Fixes"},
    {"type": "perf", "section": "Performance"},
    {"type": "refactor", "section": "Code Refactoring"},
    {"type": "docs", "section": "Documentation"}
  ]
}

Commit Type to Version Bump

提交类型与版本升级规则

Commit Type	Version Bump	CHANGELOG Section
`feat:`	Minor	Features
`fix:`	Patch	Bug Fixes
`feat!:`	Major	Features (with BREAKING CHANGE)
`BREAKING CHANGE:`	Major	Breaking Changes
`chore:`	None	(hidden)
`docs:`	None	Documentation
`refactor:`	None	Code Refactoring
`perf:`	Patch	Performance

提交类型	版本升级类型	CHANGELOG 章节
`feat:`	次要版本（Minor）	新功能
`fix:`	补丁版本（Patch）	Bug修复
`feat!:`	主要版本（Major）	新功能（包含破坏性变更）
`BREAKING CHANGE:`	主要版本（Major）	破坏性变更
`chore:`	无升级	（隐藏）
`docs:`	无升级	文档更新
`refactor:`	无升级	代码重构
`perf:`	补丁版本（Patch）	性能优化

Manifest File

清单文件

The

.release-please-manifest.json

tracks current versions:

json

{
  "package-a": "1.2.3",
  "package-b": "2.0.0"
}

Important: This file is auto-updated by release-please. Manual edits should only be done for:

Initial bootstrapping
Resetting after tag migration

.release-please-manifest.json

用于跟踪当前版本：

json

{
  "package-a": "1.2.3",
  "package-b": "2.0.0"
}

注意： 此文件由release-please自动更新。仅在以下场景下手动编辑：

初始引导配置
标签迁移后重置版本

GitHub Actions Workflow

GitHub Actions 工作流

Minimal Workflow

最简工作流

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

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

With Custom Token (Required for Triggering Other Workflows)

使用自定义Token（触发其他工作流时必填）

yaml

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

Use a PAT if you need release PRs to trigger other workflows (e.g., CI checks).

yaml

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

如果需要发布PR触发其他工作流（如CI检查），请使用个人访问令牌（PAT）。

Adding a New Package to Monorepo

为单体仓库添加新包

Update
release-please-config.json
:

json

{
  "packages": {
    "new-package": {
      "component": "new-package",
      "release-type": "simple",
      "extra-files": ["new-package/.version-file.json"],
      "changelog-sections": [...]
    }
  }
}

Update
.release-please-manifest.json
:

json

{
  "new-package": "1.0.0"
}

Create initial version file in the package if needed.

更新
release-please-config.json
：

json

{
  "packages": {
    "new-package": {
      "component": "new-package",
      "release-type": "simple",
      "extra-files": ["new-package/.version-file.json"],
      "changelog-sections": [...]
    }
  }
}

更新
.release-please-manifest.json
：

json

{
  "new-package": "1.0.0"
}

在包目录中创建初始版本文件（如需要）。

Migrating from Shared Tags to Component Tags

从共享标签迁移到组件标签

When transitioning from

v1.0.0

style tags to

component-v1.0.0

Add
```
"include-component-in-tag": true
```
to config
Add
```
"component": "package-name"
```
to each package
Old tags (
```
v1.0.0
```
) will be ignored
New releases will create component-specific tags
Close any pending combined release PRs

Note: Release-please will scan for component-specific tags. First run after migration will create release PRs for all packages with changes since the manifest version.

当从

v1.0.0

格式的标签迁移到

component-v1.0.0

格式时：

在配置中添加
```
"include-component-in-tag": true
```
为每个包添加
```
"component": "package-name"
```
旧标签（
```
v1.0.0
```
）将被忽略
新发布将创建组件专属标签
关闭所有待处理的合并发布PR

注意： Release-please会扫描组件专属标签。迁移后的首次运行将为所有自清单版本以来有变更的包创建发布PR。

Troubleshooting

故障排除

Workflow Succeeds but No PR Created

工作流成功但未创建PR

Check:

Are there releasable commits since last release tag?
Do commits follow conventional format?
Is the package path correct in config?

检查以下内容：

自上次发布标签以来是否有可发布的提交？
提交是否遵循约定式提交格式？
配置中的包路径是否正确？

Version Not Bumping

版本未升级

Check:

Commit type (feat/fix vs chore/docs)
Commit scope matches package path
Conventional commit format is correct

检查以下内容：

提交类型（feat/fix 与 chore/docs的区别）
提交范围是否与包路径匹配？
约定式提交格式是否正确？

Wrong Version in Extra Files

额外文件中的版本不正确

Ensure

extra-files

paths are correct relative to repo root, not package root:

json

// Correct
"extra-files": ["my-package/.claude-plugin/plugin.json"]

// Wrong (if package path is "my-package")
"extra-files": [".claude-plugin/plugin.json"]

确保

extra-files

的路径是相对于仓库根目录的，而非包根目录：

json

// 正确
"extra-files": ["my-package/.claude-plugin/plugin.json"]

// 错误（如果包路径为"my-package"）
"extra-files": [".claude-plugin/plugin.json"]

Quick Reference

快速参考

Conventional Commit Format

约定式提交格式

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

[optional body]

[optional footer(s)]

Examples:

bash

feat(auth): add OAuth2 support
fix(api): handle timeout edge case
feat(cli)!: redesign command interface

BREAKING CHANGE: Commands now use subcommand syntax.

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

[可选正文]

[可选页脚]

示例：

bash

feat(auth): 新增OAuth2支持
fix(api): 处理超时边缘情况
feat(cli)!: 重新设计命令界面

BREAKING CHANGE: 命令现在使用子命令语法。

Version Bump Rules

版本升级规则

Pattern	Bump
`feat:`	Minor (1.0.0 → 1.1.0)
`fix:`	Patch (1.0.0 → 1.0.1)
`!` suffix or `BREAKING CHANGE:`	Major (1.0.0 → 2.0.0)
`chore:` , `docs:` , `style:` , `test:`	No bump

模式	升级类型
`feat:`	次要版本（1.0.0 → 1.1.0）
`fix:`	补丁版本（1.0.0 → 1.0.1）
后缀 `!` 或包含 `BREAKING CHANGE:`	主要版本（1.0.0 → 2.0.0）
`chore:` , `docs:` , `style:` , `test:`	无升级

Useful Commands

实用命令

bash

undefined

bash

undefined

Check latest release-please-action version

检查最新的release-please-action版本

curl -s https://api.github.com/repos/googleapis/release-please-action/releases/latest | jq -r '.tag_name'

List pending release PRs

列出待处理的发布PR

gh pr list --label "autorelease: pending"

View recent workflow runs

查看近期工作流运行记录

gh run list --workflow=release-please.yml --limit=5

Check failed workflow logs

查看失败的工作流日志

gh run view <run-id> --log-failed

undefined

gh run view <run-id> --log-failed

undefined

release-please-configuration

Original

Translation

Release-Please Configuration

Release-Please 配置

Core Files

核心文件

Monorepo Configuration

单体仓库配置

Critical Settings for Monorepos

单体仓库关键配置

Common Failure: Duplicate Release Tags

常见问题：重复发布标签

Common Failure: Multiple Paths Warning

常见问题：多路径警告

Release Types

发布类型

Extra Files for Custom Version Locations

自定义版本位置的额外文件

Changelog Configuration

变更日志配置

Standard Changelog Sections

标准变更日志章节

Commit Type to Version Bump

提交类型与版本升级规则

Manifest File

清单文件

GitHub Actions Workflow

GitHub Actions 工作流

Minimal Workflow

最简工作流

With Custom Token (Required for Triggering Other Workflows)

使用自定义Token（触发其他工作流时必填）

Adding a New Package to Monorepo

为单体仓库添加新包

Migrating from Shared Tags to Component Tags

从共享标签迁移到组件标签

Troubleshooting

故障排除

Workflow Succeeds but No PR Created

工作流成功但未创建PR

Version Not Bumping

版本未升级

Wrong Version in Extra Files

额外文件中的版本不正确

Quick Reference

快速参考

Conventional Commit Format

约定式提交格式

Version Bump Rules

版本升级规则

Useful Commands

实用命令

Check latest release-please-action version

检查最新的release-please-action版本

List pending release PRs

列出待处理的发布PR

View recent workflow runs

查看近期工作流运行记录

Check failed workflow logs

查看失败的工作流日志

Resources

参考资源