release-please-configuration

Release-Please モノレポの設定

コンポーネント単位のタグ付け、パッケージごとの extra-files、連動するバージョン、共有タグからコンポーネントタグへの移行など、モノレポ固有の release-please 戦略です。単一リポジトリのワークフロー／マニフェスト／設定の形式、Conventional Commits に基づくバージョン更新ルール、コンプライアンス監査については、 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: トレーラーに基づく一時的な上書き — 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	はい（モノレポ）	v1.0.0 ではなく package-a-v1.0.0 タグを作成します
component	はい（モノレポ）	各パッケージの一意な識別子です。すべてのパッケージに設定する必要があります
separate-pull-requests	推奨	複数パッケージをまとめたリリース PR ではなく、パッケージごとのリリース 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）を作成しようとします。

1. ルートレベルに include-component-in-tag: true がない
2. 各パッケージに 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）に ${version} — または ${component}／${scope} — が含まれており、グループ化されたリリース PR（separate-pull-requests: false）で使用されています。グループ化された PR は多数のパッケージにまたがるため、置き換えに使える単一のバージョン／コンポーネントがなく、パターンから何も続かないタイトル（例：後ろに何も付かない chore: release）が生成されます。タグ付けの実行時、release-please はマージ済み PR のタイトルを同じパターンで再解析し、それがどのリリースを表すかを復元します。生成されたタイトルはパターンに一致しないため、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 はパッケージのパスを自動的に先頭に追加します。

よくある間違い：

1. 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"}
]

2. パッケージのパスを自分で先頭に追加する（二重に追加されます）：

// 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"（文字列で問題ありません）

モノレポへの新しいパッケージの追加

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

2. .release-please-manifest.json を更新します：

{
  "new-package": "1.0.0"
}

3. 必要に応じて、パッケージ内に初期バージョンファイルを作成します。

標準の changelog-sections セットとリリースタイプの表については、 configure-plugin:configure-release-please を参照してください。

共有タグからコンポーネントタグへの移行

v1.0.0 形式のタグから component-v1.0.0 形式のタグに移行する場合：

1. 設定に "include-component-in-tag": true を追加します
2. 各パッケージに "component": "package-name" を追加します
3. 古いタグ（v1.0.0）は無視されます
4. 新しいリリースではコンポーネント固有のタグが作成されます
5. 保留中の複合リリース PR をすべてクローズします

注： Release-please はコンポーネント固有のタグを検索します。移行後の最初の実行では、マニフェストのバージョン以降に変更があったすべてのパッケージについて、リリース PR が作成されます。

モノレポのトラブルシューティング

あるパッケージの PR が作成されない（ほかのパッケージは正常）

確認事項：

1. そのパッケージのパスを対象とするリリース可能なコミットが、最後のコンポーネントタグ以降にありますか？
2. コミットのスコープはパッケージのパスと一致していますか？
3. パッケージの component は設定されており、一意ですか？

パッケージの追加ファイル内のバージョンが誤っている

パッケージの extra-files のパスが、リポジトリのルートではなくパッケージディレクトリを基準としていることを確認してください（release-please がパッケージのパスを先頭に追加します）：

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

単一リポジトリのトラブルシューティング（PR がまったく作成されない、バージョンが更新されない、リリース PR で CI が実行されない）については、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

リソース

• マニフェストリリースガイド — モノレポの正式なリファレンス
• Release-Please ドキュメント
• Release-Please アクション
• configure-plugin:configure-release-please — 単一リポジトリの標準、バージョン更新ルール、コンプライアンス監査