release-please

release-please

概要

release-please は、Conventional Commit メッセージを分析して、バージョン管理とリリースを自動化します。

1. デフォルトブランチに Conventional Commit を プッシュします
2. release-please がリリース PR を作成／更新し、バージョンの更新と変更履歴を記載します
3. リリース PR を マージして、GitHub リリースをトリガーします
4. リリースが作成されると、公開ステップが実行されます（npm、PyPI、crates.io など）

release-please は、バージョンの決定、変更履歴の生成、Git タグの作成を処理します。適切なコミットメッセージを書けば、あとは自動で行われます。

コミットメッセージの作成支援

ユーザーがコミットメッセージの作成を手伝ってほしいと頼んだ場合（パイプラインのセットアップではない場合）：

1. 変更内容を尋ねる — 「何を、なぜ変更しましたか？」（すでに説明されている場合は省略）
2. タイプを提案する — 以下のタイプ表から選び、適切な理由を説明します
3. メッセージの草案を作成する — 完全なコミットメッセージ（ヘッダー＋必要に応じた本文＋フッター）を書きます
4. 確認する — ユーザーが承認または調整できるよう提示します

変更が破壊的な場合は、移行への影響を説明する BREAKING CHANGE: フッターを必ず含めてください。

パイプラインのセットアップ手順

ユーザーが release-please のセットアップを希望する場合は、この対話プロトコルに従ってください。

.github/workflows/release.yml（または同様のファイル）がすでに存在する場合は、まずそれを読み、references/workflow-templates.md のテンプレートと比較し、全面的に置き換えるのではなく具体的な改善案を提示してください。よくある改善点は、コンカレンシーグループの欠落、release_created による公開処理のゲート設定漏れ、冪等性のある公開チェックの欠落、権限の範囲が広すぎることです。

ステップ 1：プロジェクトの種類を検出する

リポジトリ内のパッケージマニフェストを確認します。

ファイル	リリースタイプ
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 を使用します。

ステップ 2：設定に関する質問をする

以下の質問をします（すでに回答済み、または文脈から明らかなものは省略します）。

1. モノレポですか？（サブディレクトリに複数のパッケージがあるか）
2. デフォルトブランチは何ですか？（デフォルト：main）
3. プレリリースに対応する必要がありますか？（手動での alpha/beta/rc リリース）
4. どこに公開しますか？（npm、GitHub Packages、PyPI、Maven Central、crates.io、Docker、公開しない）
5. 現在のバージョンは何ですか？（パッケージマニフェストを確認します。デフォルト：0.0.0）

ステップ 3：ファイルを生成する

回答に基づいて、3 つのファイルを作成します。

release-please-config.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 を調整します。モノレポの場合は、packages の下に component 名を付けた複数の項目を追加します。

.release-please-manifest.json

{
  ".": "1.0.0"
}

現在リリース済みのバージョンを設定します。新規プロジェクトでは "0.0.0" を使用します。

.github/workflows/release.yml

Node.js → npm の公開レジストリ（最も一般的なケース）では、以下の基本テンプレートを使用します。

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 タグでのビルド＋プッシュ）
• モノレポ（パッケージごとの公開ジョブ）
• プレリリースパターン（バージョン解決を伴う workflow_dispatch）

必ずカスタマイズしてください。

• デフォルトブランチが異なる場合は、main を実際のデフォルトブランチに置き換えます
• Node のバージョン、Python のバージョン、Java のバージョンなどを調整します
• レジストリ固有のシークレット設定を追加します
• プレリリースに対応する必要がある場合は、references/workflow-templates.md のプレリリース用テンプレートを使用します

設定のクイックリファレンス

オプション	デフォルト	目的
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	パッケージごとに PR を作成します（モノレポ）
draft	false	リリース PR をドラフトとして作成します
extra-files	[]	更新するバージョン文字列を含む追加ファイル
changelog-sections	（デフォルト）	変更履歴に表示する種類をカスタマイズします

モノレポのクイックセットアップ

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

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

コミットスコープにはコンポーネント名を使用します：feat(core): add streaming support

すべての設定オプションについては、references/config-options.md を参照してください。

コミットメッセージガイド

release-please はコミットメッセージを読み取り、バージョンの更新内容を決定して変更履歴を生成します。デフォルトブランチへのすべてのコミットは、Conventional Commits に従う必要があります。

形式

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

[optional body]

[optional footer(s)]

• 命令形の現在形を使用します：「added」ではなく「add」
• 説明の最初の文字は大文字にしません
• 末尾にピリオドを付けません

種類 → バージョン更新

種類	更新	リリースのトリガー
feat	マイナー	はい
fix	パッチ	はい
deps	パッチ	はい
refactor	—	いいえ
perf	—	いいえ
test	—	いいえ
docs	—	いいえ
style	—	いいえ
chore	—	いいえ
build	—	いいえ
ci	—	いいえ

破壊的変更（! または BREAKING CHANGE: フッターを含むすべての種類）→ メジャー更新。

破壊的変更の例

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.

特殊なフッター

フッター	目的
BREAKING CHANGE: <desc>	メジャーバージョン更新をトリガーします
Release-As: x.x.x	特定のバージョン番号を指定します

クイック例

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

AI の共同作成者トレーラーを追加しない

コミットメッセージにAI エージェントの Co-Authored-By トレーラーを絶対に追加しないでください。変更履歴と Git 履歴が不要な情報で汚れてしまいます。

15 以上の例、スコープガイド、アンチパターンを含むコミット規約の完全なリファレンスについては、references/commit-conventions.md を参照してください。

ベストプラクティス

スカッシュマージ

機能ブランチにスカッシュマージを使用するよう、リポジトリを設定してください。これにより各 PR が 1 つの Conventional Commit を生成し、変更履歴を整理できます。スカッシュコミットメッセージには PR のタイトルを使用するよう設定してください（タイトルは Conventional Commit のメッセージにしてください）。

権限

GitHub Actions には最低限 contents: write と pull-requests: write が必要です。必要に応じて、公開ステップ用に packages: write または id-token: write を追加してください。最小権限の原則に従い、ワークフローレベルではなくジョブごとに権限を付与してください。

同時実行

リリースワークフローでは、必ず cancel-in-progress: false を設定してください。リリースの途中でキャンセルすると、タグはあるのにリリースがない、PR の状態が不整合になるなど、一部の状態だけが残ることがあります。

公開のゲーティング

release-please ジョブ自体では絶対に公開しないでください。release_created == 'true' を条件とする別の publish ジョブを使用してください。これにより関心事を分離し、再試行が容易になります。

冪等な公開

公開前に、バージョンがレジストリにすでに存在するか確認してください。これにより、ワークフローの再実行時にエラーが発生するのを防げます。

- 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

既存プロジェクトのブートストラップ

既存のリリースがあるプロジェクトに release-please を追加する場合：

1. .release-please-manifest.json を現在のバージョンに設定します
2. chore: コミットでセットアップ PR をマージします
3. release-please は、その後のコミットに基づいて次のリリース PR を作成します
4. または、Release-As: x.x.x フッターを使用して開始バージョンを指定します

トラブルシューティング

リリース PR が作成されない

• 最後のリリース以降のコミットに、リリース対象の種類（feat、fix、deps）が少なくとも 1 つ含まれていることを確認します
• コミットが正しいブランチにあることを確認します（ワークフローのトリガーと一致している必要があります）
• release-please-config.json とマニフェストが存在し、有効な JSON であることを確認します
• Actions のログで権限エラーを確認します

バージョンの誤った更新

• コミットメッセージを確認します。chore: ではリリースが行われず、feat: ではマイナーバージョンが更新されます
• 予期しないメジャーバージョンの更新を引き起こす可能性がある BREAKING CHANGE: フッターがないか確認します
• 必要に応じて Release-As: x.x.x フッターで上書きします

プレリリースのフロー

• プレリリースでは、自動的なプッシュトリガーではなく workflow_dispatch を使用します
• プレリリース識別子は現在のバージョンに追加されます：1.2.3-alpha.1
• プレリリースには next npm タグ（または同等のタグ）を、安定版には latest を使用します
• プレリリース用テンプレートは references/workflow-templates.md を参照してください

トークン／権限の問題

• デフォルトの GITHUB_TOKEN は release-please の PR とリリースで使用できます
• 外部レジストリへの公開には、専用のシークレット（NPM_TOKEN など）が必要です
• GitHub Packages への公開では、packages: write 権限を持つ GITHUB_TOKEN を使用します
• PyPI では、API トークンの代わりに信頼されたパブリッシャーを使用します

参考資料

参考資料	説明
references/commit-conventions.md	例とアンチパターンを含む、Conventional Commits の完全な仕様
references/workflow-templates.md	9 つのエコシステム向けの完全なワークフローテンプレート
references/config-options.md	すべての設定オプション、リリースタイプ、Action の入力／出力
release-please GitHub	公式ドキュメント
Conventional Commits	仕様