semantic-release

semantic-release

自己進化型スキル：このスキルは使用を重ねることで改善されます。手順に誤りがある、パラメーターが変化している、または回避策が必要になった場合は、先延ばしにせず、ただちにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

概要

**semantic-release v25+（Node.js）**を使用し、2025年のベストプラクティスに沿ってセマンティックバージョニングとリリース管理を自動化します。@semantic-release/exec プラグインを介して、あらゆる言語（JavaScript、TypeScript、Python、Rust、Go、C++など）に対応します。複数リポジトリ構成向けの共有可能な設定を作成したり、個々のプロジェクトを自動リリースで初期化したり、OIDC のトラステッドパブリッシングを利用する GitHub Actions ワークフローを設定したりできます。

重要：このスキルでは semantic-release（Node.js）のみを使用し、Python プロジェクトでも python-semantic-release は使用しません。その理由は、コミュニティの規模が23.5倍大きく、採用数が100倍以上で、将来にわたって安心して利用できるためです。

このスキルを使用する場面

次の場合に呼び出してください。

• 新しいプロジェクト（あらゆる言語）のローカルリリースを設定する
• 組織全体で使用する共有可能な semantic-release 設定を作成する
• 既存のプロジェクトを2025年の semantic-release パターンに移行する
• semantic-release の設定やバージョン更新の問題をトラブルシューティングする
• Python プロジェクトを設定する（python-semantic-release ではなく Node.js の semantic-release を使用します）
• GitHub Actions を設定する（任意のバックアップ用途。速度の面から、主な方法としては推奨しません）
• release-plz を使用する Rust ワークスペースを設定する（Rust リファレンスを参照）

Node.js semantic-release を選ぶ理由

GitHub スター数22,900 - 大規模で活発なコミュニティです
週間ダウンロード数190万 - 採用実績があります
採用プロジェクト数126,000 - 大規模環境で十分に検証されています
公式プラグイン35以上 - 豊富なエコシステムがあります
マルチ言語対応 - @semantic-release/exec を介してあらゆる言語で動作します

python-semantic-release は使用しないでください。 コミュニティの規模は23.5分の1（スター数975対22,900）で、採用数は約100分の1にとどまり、semantic-release 組織とは関係がありません。

---

リリースワークフローの方針：ローカル優先

デフォルトの方法：GitHub Actions ではなく、ローカルでリリースを実行します。

ローカルリリースを選ぶ理由

主な理由：GitHub Actions は時間がかかります

• ⏱️ GitHub Actions：リリース完了まで2〜5分待ちます
• ⚡ ローカルリリース：すぐに結果が返り、ファイルも更新されます
• 🔄 ワークフローをすぐに続行できます。CI/CD の完了を待つ必要はありません

その他のメリット：

• ✅ ローカルファイルがすぐに同期される - package.json、CHANGELOG.md、タグがただちに更新されます
• ✅ プルが不要 - リリース後に git pull せず、そのまま作業を続けられます
• ✅ ドライランテスト - npm run release:dry でリリース前に変更を確認できます
• ✅ オフラインで実行可能 - CI/CD に依存せずリリースできます
• ✅ イテレーションが高速 - CI のログを通さず、リリースの問題をすぐにデバッグできます

GitHub Actions：任意のバックアップ用途のみ

GitHub Actions のワークフローは主な方法ではなく、任意の自動化手段として提供されています。

• 必要に応じて、チーム内で一貫性を保つために使用します
• ローカル環境を利用できない場合のバックアップとして使用します
• 速度の面から、主なワークフローとしては推奨しません

認証の設定

gh auth login
# Browser authentication once
# Credentials stored in keyring
# All future releases: zero manual intervention

GitHub プラグインの機能を使用したローカルの semantic-release では、手動での介入をこれ以上減らせません。

mise [env] による複数アカウント認証

GitHub の複数アカウントを設定している場合は、mise の [env] を使用して、ディレクトリごとに GH_TOKEN を設定します。

# ~/your-project/.mise.toml
[env]
GH_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}"
GITHUB_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}"

これにより gh CLI のグローバル認証が上書きされ、各ディレクトリで semantic-release が正しいアカウントを使用するようになります。

設定全体については、mise-configuration スキルを参照してください。

mise タスクの検出

.mise.toml にリリースタスクがある場合は、npm run より mise run を優先します。

優先度	条件	コマンド
1	.mise.toml に [tasks.release:*] がある	mise run release:version
2	package.json に scripts.release がある	npm run release
3	グローバルの semantic-release	semantic-release --no-ci

mise ワークフローの完全な例は、Python ガイドを参照してください。

GitHub Actions ポリシー

重大：GitHub Actions ではテストやリントを実行しないでください。 ポリシーの全文は CLAUDE.md を参照してください。

禁止	許可
pytest、npm test、cargo test	semantic-release
ruff、eslint、clippy、prettier	CodeQL、npm audit
mypy	デプロイ、Dependabot

---

関心の分離（4 階層アーキテクチャ）

semantic-release の設定は、階層的で組み合わせ可能なパターンに従います。

レベル 1：スキル - ${CLAUDE_PLUGIN_ROOT}/skills/semantic-release/（汎用テンプレート、システム全体で使用するツール） レベル 2：ユーザー設定 - ~/semantic-release-config/（@username/semantic-release-config） レベル 3：組織設定 - npm レジストリ（@company/semantic-release-config） レベル 4：プロジェクト設定 - プロジェクトのルートにある .releaserc.yml

設定の優先順位

Level 4 (Project) → overrides → Level 3 (Org) → overrides → Level 2 (User) → overrides → Defaults

---

Conventional Commits 形式

semantic-release はコミットメッセージを分析して、バージョンの更新内容を決定します。

<type>(<scope>): <subject>

バージョン更新ルール（デフォルト）

• feat: → MINOR バージョン更新（0.1.0 → 0.2.0）
• fix: → PATCH バージョン更新（0.1.0 → 0.1.1）
• BREAKING CHANGE: または feat!: → MAJOR バージョン更新（0.1.0 → 1.0.0）
• docs:、chore:、style:、refactor:、perf:、test: → バージョン更新なし（デフォルト）

リリースノートへの表示（重要）

警告：@semantic-release/release-notes-generator（Angular プリセット）は、次のタイプのみをリリースノートに含めます。

• feat: → 機能セクション
• fix: → バグ修正セクション
• perf: → パフォーマンス改善セクション

その他のタイプ（docs:、chore:、refactor: など）は、設定に応じてリリースを発生させますが、リリースノートには表示されません。

推奨：リリースノートに表示させるドキュメントの変更には、次を使用してください。

fix(docs): description of documentation improvement

これにより、コミットは「バグ修正」セクションに表示されます。同時に、ドキュメントの不足を修正することは修正に当たるため、意味的にも正確です。

マーケットプレイスプラグインの設定（常に更新）

Claude Code マーケットプレイスのプラグインでは、ユーザーが更新を受け取るために、変更のたびにバージョン更新が必要です。

オプション A：共有可能な設定（公開済みの場合）

# .releaserc.yml
extends: "@terryli/semantic-release-config/marketplace"

オプション B：インライン設定

# .releaserc.yml
plugins:
  - - "@semantic-release/commit-analyzer"
    - releaseRules:
        # Marketplace plugins require version bump for ANY change
        - { type: "docs", release: "patch" }
        - { type: "chore", release: "patch" }
        - { type: "style", release: "patch" }
        - { type: "refactor", release: "patch" }
        - { type: "test", release: "patch" }
        - { type: "build", release: "patch" }
        - { type: "ci", release: "patch" }

設定後の結果：

コミットタイプ	リリースタイプ
feat:	minor（デフォルト）
fix:、perf:、revert:	patch（デフォルト）
docs:、chore:、style:、refactor:、test:、build:、ci:	patch（設定済み）

マーケットプレイスプラグインにこの設定が必要な理由：プラグインの更新はバージョンタグを通じて配布されます。バージョンを更新しないと、コンテンツが変更されていても、/plugin update を実行したユーザーには変更が表示されません。

必須：すべてのリリースでバージョンをインクリメントする

リリース前の検証：semantic-release を実行する前に、最後のタグ以降にリリース対象のコミットがあることを確認してください。バージョンがインクリメントされないリリースは無効です。

自律的な確認手順：

1. 最後のタグ以降のコミットを一覧表示する：HEAD と最新のバージョンタグを比較します
2. コミットの種類を特定する：feat:、fix:、または BREAKING CHANGE: のプレフィックスを検索します
3. リリース対象のコミットが見つからない場合 → 停止 - リリースを続行しないでください
4. ユーザーに伝えます：「前回のリリース以降、バージョンを上げるコミットがありません。リリース対象の変更には feat: または fix: のプレフィックスを使用してください。」

コミットの種類の選び方：

• 既存の動作を改善する変更（バグ修正、機能強化、使用方法に影響するドキュメントの修正）には fix: を使用します
• 新しい機能や重要な追加には feat: を使用します
• 本当にリリースに値しない変更に限り、chore:、docs:、refactor: を使用します

重要な理由：バージョンがインクリメントされないリリースは混乱を招きます。ユーザーがリリースを区別できず、パッケージマネージャーが古いバージョンをキャッシュする可能性があり、変更履歴の内容も意味をなさなくなります。

MAJOR バージョンの破壊的変更の確認

トリガー：コミット内の BREAKING CHANGE: フッター、または feat!: / fix!: プレフィックス。

MAJOR が検出されると、このスキルは3 段階の確認ワークフローを実行します。

1. 検出：コミット内の破壊的変更を示すマーカーを検索します
2. 分析：3 つのサブエージェント（ユーザーへの影響、API 互換性、移行）を並行して起動します
3. 確認：続行／ダウングレード／中止の選択肢を含む AskUserQuestion を提示します

サブエージェントのプロンプト、判断フロー、出力例を含む詳しい説明は、MAJOR Confirmation Workflow を参照してください。

例

機能（MINOR）：

feat: add BigQuery data source support

バグ修正（PATCH）：

fix: correct timestamp parsing for UTC offsets

破壊的変更（MAJOR）：

feat!: change API to require authentication

BREAKING CHANGE: All API calls now require API key in Authorization header.

---

ドキュメントのリンク

ドキュメントの変更をリリースノートに自動で含めます。.releaserc.yml に追加してください。

- - "@semantic-release/exec"
  - generateNotesCmd: "node plugins/itp/skills/semantic-release/scripts/generate-doc-notes.mjs ${lastRelease.gitTag}"

ADR、設計仕様、スキル、プラグインの README を検出します。詳しくは Doc Release Linking を参照してください。

注：@semantic-release/exec プラグインでは Lodash テンプレート（${var}）を使用します。これは bash のデフォルト構文（${VAR:-default}）およびサブシェル構文（$(cmd)）と競合します。推奨される修正方法：タスクランナーがリリース後の手順をすでに処理している場合は、successCmd を完全に削除してください。詳しくは トラブルシューティング：Lodash テンプレートの競合 を参照してください。

---

クイックスタート

前提条件

確認項目	コマンド	対処
gh CLI の認証	gh auth status	gh auth login
ディレクトリ用の GH_TOKEN	gh api user --jq '.login'	認証 を参照してください
Git リモートが HTTPS	git remote get-url origin	git-ssh-to-https
semantic-release のグローバルインストール	command -v semantic-release	トラブルシューティング を参照してください

プロジェクトを初期化する

./scripts/init-project.mjs --project   # Initialize current project
./scripts/init-project.mjs --user      # Create user-level shareable config
./scripts/init-project.mjs --help      # See all options

リリースの実行

優先度	条件	コマンド
1	.mise.toml にリリースタスクがある	mise run release:version / mise run release:full
2	package.json にスクリプトがある	npm run release:dry（プレビュー） / npm run release
3	グローバル CLI	semantic-release --no-ci

完全な 4 フェーズのプロセスについては、ローカルリリースのワークフローを参照してください。

Python プロジェクト

バージョン管理は semantic-release が処理します。PyPI への公開については、pypi-doppler skillを参照してください。

バージョンパターン（importlib.metadata を使用し、ハードコードしないでください）：

from importlib.metadata import PackageNotFoundError, version
try:
    __version__ = version("your-package-name")
except PackageNotFoundError:
    __version__ = "0.0.0+dev"

Rust と Python のハイブリッドを含む完全なセットアップについては、Python プロジェクトガイドを参照してください。

GitHub Actions（任意）

主要な方法としては推奨されません（2～5 分の遅延があります）。Repository Settings → Actions → Workflow permissions → 「Read and write permissions」を有効にしてください。

---

参考ドキュメント

カテゴリ	参考資料	説明
セットアップ	認証	HTTPS 優先のセットアップ、複数アカウントのパターン
ワークフロー	ローカルリリースのワークフロー	4 フェーズのプロセス（PREFLIGHT → RELEASE → POSTFLIGHT）
言語	Python プロジェクト	Python と Rust＋Python のハイブリッドパターン
	Rust プロジェクト	release-plz、cargo-rdme による README の SSoT
設定	バージョンの整合性	SSoT としての Git タグ、マニフェストのパターン
	モノレポのサポート	Pants と mise、pnpm/npm ワークスペースを使ったポリグロットモノレポ
高度な内容	MAJOR の確認	破壊的変更の分析ワークフロー
	ドキュメントとリリースのリンク	リリースノート内の ADR／仕様書を自動リンク
ヘルプ	トラブルシューティング	よくある問題をすべてまとめています
	進化ログ	スキルの変更履歴

他のスキルへの参照：

• mise-tasks skill: polyglot-affected - Pants と mise の完全な統合ガイド
• mise-tasks skill: bootstrap-monorepo - ポリグロットモノレポの自律的なセットアップ
• pypi-doppler skill - Doppler を使ったローカル PyPI 公開

---

変更後のチェックリスト

このスキル（semantic-release）を変更した後：

1. SKILL.md と参考資料の内容が一致している
2. 新しい参考資料が「参考ドキュメント」表に記載されている
3. references/ 内で参照されているすべてのファイルが存在する
4. 変更内容を evolution-log.md に追記する
5. bun scripts/validate-plugins.mjs で検証する
6. npm run release:dry を実行して、デグレードがないことを確認する

---

トラブルシューティング

問題	原因	解決策
リリースが作成されない	タグ以降にリリース可能なコミットがない	バージョンを更新するコミットには feat: または fix: のプレフィックスを使用します
バージョンの更新が誤っている	コミット種別の不一致	Conventional Commits の形式と releaseRules を確認します
GitHub リリースが作成されない	GH_TOKEN または権限がない	トークンが設定され、repo スコープがあることを確認します
CHANGELOG が更新されない	changelog プラグインがない	@semantic-release/changelog を plugins 配列に追加します
"Authentication failed"	HTTPS と SSH のリモート設定が不一致	HTTPS に変換します：git-ssh-to-https
semantic-release が見つからない	グローバルにインストールされていない	npm install -g semantic-release
macOS で Gatekeeper にブロックされる	Node ファイルが署名されていない	トラブルシューティングを参照してください
dry-run で変更が表示されない	HEAD ですでにリリース済み	リリースを実行する前に新しいコミットを作成します
複数アカウントのトークンが競合する	ディレクトリに対して GH_TOKEN が誤っている	ディレクトリごとのトークンを mise [env] で設定します

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させてください。
3. 回避策が必要でしたか？ — 即興で対応した場合（異なるフラグや追加手順など）は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測による更新は避けてください。