release-please-configuration

Name: release-please-configuration
Author: laurigates

github.com/laurigates云与 DevOps5952 次安装1 天前更新

代码仓库

关于 release-please-configuration

用于在 monorepo 中配置 release-please 的技能，涵盖各包的组件、标签、版本文件和联动版本，也说明常见发布故障及从共享标签迁移到组件专属标签的方法。

主要功能

01配置各包的组件与标签
02设置包级 extra-files
03支持联动包版本
04排查常见发布故障
05指导共享标签迁移

适用场景

01将新包加入 monorepo 发布配置
02避免重复发布标签
03更新包文件中的版本字段
04迁移到组件专属发布标签

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laurigates/claude-plugins --skill release-please-configuration

安装后在 Claude Code 中输入/release-please-configuration确认已加载。

附带文件scripts/tests/test-grouped-pr-tagging-wedge.sh

详细介绍

Release-Please 单体仓库配置

单体仓库专用的 release-please 策略：组件标签、按软件包配置 extra-files、关联版本，以及从共享标签迁移到组件标签。如需了解单仓库工作流／清单／配置的结构、常规提交的版本提升规则以及合规审计，请使用 configure-plugin:configure-release-please。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代技能……
为多软件包仓库配置 `component`／`include-component-in-tag`	设置单仓库 release-please（工作流、清单、配置结构）——使用 `configure-plugin:configure-release-please`
将新软件包添加到单体仓库的 release-please 配置中	根据已记录的约定审计现有设置——使用 `configure-plugin:configure-release-please`
修复重复标签、多路径或按软件包不提升版本的问题	实际合并 release-please PR——使用 `release-please-pr-workflow`
从共享的 `v1.0.0` 标签迁移到 `component-v1.0.0` 标签	检测对受管理文件的手动编辑——使用 `release-please-protection`
为每个软件包设置 `extra-files`（JSON/YAML/TOML/XML 版本位置）	基于 `Release-As:` trailer 的一次性覆盖——使用 `git-commit-trailers`

核心文件

文件	用途
`release-please-config.json`	每个软件包的配置、变更日志分区、extra-files
`.release-please-manifest.json`	每个软件包／组件的当前版本
`.github/workflows/release-please.yml`	GitHub Actions 工作流（结构请参阅 `configure-plugin:configure-release-please` 中的 REFERENCE.md）

单体仓库配置

单体仓库的关键设置

{
  "$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，而不是合并创建

关联版本

如需让一组组件使用相同版本，请使用 linked-versions 插件：

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

常见故障：发布标签重复

症状： 工作流失败，并显示 Duplicate release tag: v2.0.0

原因： 所有软件包都尝试创建相同的标签（例如 v2.0.0），原因是：

根级别缺少 include-component-in-tag: true
每个软件包都缺少 component 字段

修复：

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

常见故障：多路径警告

症状： Multiple paths for : package-a, package-b

原因： component 字段为空（冒号 : 后没有内容，表示空字符串）

修复： 确保每个软件包都设置了 "component": "package-name"

常见故障：合并后的发布 PR 始终未打标签

症状： 分组发布 PR 合并后，每次运行都会中止，并显示：

There are untagged, merged release PRs outstanding - aborting

工作流日志还会出现以下提示：

pullRequestTitlePattern miss the part of '${component}'
pullRequestTitlePattern miss the part of '${scope}'

原因： 自定义的 pull-request-title-pattern（或 group-pull-request-title-pattern）在分组发布 PR 上包含 ${version}，或 ${component}／${scope}（separate-pull-requests: false）。由于分组 PR 涉及多个软件包，没有单一的版本／组件可以代入，因此模式会生成不带内容的标题（例如只有 chore: release）。在打标签阶段，release-please 会使用同一模式重新解析已合并 PR 的标题，以恢复其代表的发布内容；不带内容的标题不再匹配该模式，因此 PR 始终不会被打标签。它会一直处于 autorelease: pending 状态，而只要存在尚未打标签的已合并发布 PR，后续每次运行都会拒绝继续。

修复： 移除自定义标题模式。release-please 的默认值对分组 PR 可以正确往返处理——它们会生成可解析的标题，打标签阶段也能据此恢复发布内容。

// WRONG - ${version} on a grouped PR renders a bare, unparseable title
{
  "separate-pull-requests": false,
  "pull-request-title-pattern": "chore: release ${version}"
}

// CORRECT - omit the custom pattern; the default round-trips
{
  "separate-pull-requests": false
}

恢复：解除已合并但未打标签的 PR 卡住状态

分组发布 PR 以未经修改的标题合并后，即使移除配置可以修复后续运行，已合并的 PR 仍会卡在 autorelease: pending，导致后续运行不断中止。将其重新标记为 autorelease: tagged，让 release-please 不再将其视为待处理项，然后触发一次新的运行来创建发布：

# Create the label first if the repo lacks it — release-please only
# auto-creates `autorelease: tagged` when it successfully tags a PR.
gh label create "autorelease: tagged" --color 2A7A2A --description "release-please tagged"

# Relabel the stuck merged PR
gh pr edit $PR_NUMBER --add-label "autorelease: tagged" --remove-label "autorelease: pending"

# Dispatch a fresh run — with no tags cut, it recomputes the same releases
# into a new, parseable release PR (or tags directly on the next merge).
gh workflow run release-please.yml

卡住的 PR 没有创建任何标签，因此 release-please 会在下次运行时重新计算出完全相同的一组发布；重新标记只会移除“待处理”阻碍。

为自定义版本位置设置按包配置的 `extra-files`

对于 JSON 文件，必须使用包含 type、path 和 jsonpath 的对象格式：

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

关键要点： 对于单体仓库中的包，extra-files 路径相对于包目录，而不是仓库根目录。Release-please 会自动在路径前添加包路径。

常见错误：

对 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"}
]

自行在路径前添加包路径（这会导致路径重复）：

// WRONG - path becomes my-plugin/my-plugin/.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"}
]

文件类型格式：

文件类型	格式
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"`（字符串即可）

向单体仓库添加新包

更新 release-please-config.json：

{
  "packages": {
    "new-package": {
      "component": "new-package",
      "release-type": "simple",
      "extra-files": [
        {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
      ],
      "changelog-sections": [...]
    }
  }
}

更新 .release-please-manifest.json：

{
  "new-package": "1.0.0"
}

如果需要，在包中创建初始版本文件。

标准的 changelog-sections 集合和发布类型表，请参见 configure-plugin:configure-release-please。

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

从 v1.0.0 样式的标签迁移到 component-v1.0.0 时：

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

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

单体仓库故障排查

未创建某个包的 PR（其他包正常）

检查：

自该包上一个组件标签以来，是否存在作用域为该包路径的可发布提交？
提交作用域是否与包路径匹配？
该包是否设置了唯一的 component？

包的额外文件中的版本错误

确保包的 extra-files 路径相对于包目录，而不是仓库根目录（release-please 会在路径前添加包路径）：

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

如需排查单仓库问题（完全没有创建 PR、版本未递增、CI 未在发布 PR 上运行），请参见 configure-plugin:configure-release-please。

快速参考

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

# List pending release PRs (per-component in a monorepo)
gh pr list --label "autorelease: pending"

# View recent workflow runs
gh run list --workflow=release-please.yml --limit=5

# Inspect a package's current version in the manifest
jq -r '."my-package"' .release-please-manifest.json

资源

Manifest Releaser 指南 — 单体仓库的权威参考
Release-Please 文档
Release-Please Action
configure-plugin:configure-release-please — 单仓库标准、版本递增规则、合规审计

支持 Markdown

登录后评论

基本信息

作者: laurigates
仓库: laurigates/claude-plugins
分类: 云与 DevOps
安装次数: 52
GitHub Stars: 59

报告问题