Changesets でリリースワークフローを簡単に

npm パッケージの公開には、カスタムスクリプト、手動でのバージョン更新、前回のリリース以降にどのパッケージが変更されたかを覚えておく必要があるべきではありません。しかし、多くのチームは依然として、最悪のタイミングで壊れる脆弱なリリースプロセスを継ぎはぎで作成しています。

Changesets は、コントリビューション時にリリース意図をキャプチャし、残りを自動化することでこの問題を解決します。この記事では、npm trusted publishing、Changesets によるモノレポのバージョン管理、GitHub Actions によるパッケージリリースなど、メンテナンスの負担なく最新の Changesets リリースワークフローを構築する方法を説明します。

Changesets リリースワークフローの基本

ワークフローは3つのフェーズに従います:

1. コントリビューターが changeset ファイルを追加し、何が変更されたか、どの程度重要か(patch、minor、major)を記述します
2. CI がバージョニング PR を作成し、すべての changeset をバージョンバンプと changelog エントリに集約します
3. PR をマージすると、適切な来歴情報とともに npm への公開がトリガーされます

各 changeset は .changeset/ 内の markdown ファイルで、影響を受けるパッケージと semver バンプタイプを指定するフロントマター、および人間が読める要約が含まれています。複数の changeset が存在する場合、Changesets はパッケージごとに必要な最高のバージョンバンプを計算します。2つの minor 変更が2回の minor バンプになることはありません。

モノレポの場合、これは非常に重要です。Changesets は、あるワークスペースパッケージがリリースされる別のパッケージに依存している場合、内部依存関係の更新を自動的に処理します。

GitHub Actions によるパッケージリリース:最新のアプローチ

ほとんどのチュートリアルでは、NPM_TOKEN シークレットを使用したワークフローが紹介されています。このアプローチは機能しますが、セキュリティリスクを伴います。長期間有効なトークンは漏洩する可能性があり、手動でのローテーションが必要です。

OIDC トークンを使用した npm trusted publishing が現在推奨される方法です。認証情報を保存する代わりに、GitHub Actions ワークフローは公開ステップ中に npm から直接短期間有効なトークンをリクエストします。トークンはそのジョブの間だけ存在し、抽出や再利用はできません。

これを有効にするには:

1. npm のパッケージ設定で、npm パッケージを GitHub リポジトリにリンクします
2. id-token: write 権限でワークフローを設定します
3. 来歴情報(provenance)が有効になっていることを確認します(npm は trusted publisher に対して自動的に生成できます。または、新しい CLI では --provenance フラグを使用します)

npm provenance は、パッケージがリポジトリの特定のコミットからビルドされたことを証明する暗号化された証明を追加します。ユーザーは、公開されたアーティファクトがどのソースコードから生成されたかを正確に検証できます。

知っておくべき現在の制限: npm trusted publishing には公開リポジトリが必要です。プライベートリポジトリでは、依然として従来の NPM_TOKEN アプローチが必要です。さらに、公式の changesets/action は OIDC のサポートが進化中です。最新の統合パターンについては、現在のドキュメントを確認してください。

Changesets によるモノレポのバージョン管理

Changesets は最初からモノレポ向けに設計されています。.changeset/config.json の主要な設定オプションは、マルチパッケージの動作を制御します:

• linked: 常に同じバージョン番号を共有すべきパッケージをグループ化します
• fixed: linked に似ていますが、1つだけが変更された場合でもすべてのパッケージが一緒にバンプされます
• updateInternalDependencies: 依存関係が更新されたときに依存パッケージが patch バンプを受けるかどうかを制御します

コントリビューターがモノレポで changeset CLI を実行すると、変更が影響するパッケージを選択します。バージョニング PR には、どのパッケージがどのバージョンでリリースされるかが正確に表示されます。

一般的な CI の落とし穴

権限の問題がワークフロー失敗の最も一般的な原因です。GitHub トークンには、PR の作成とタグのプッシュのための書き込みアクセスが必要です。npm 公開の場合、トークン(または OIDC 設定)がスコープ内のすべてのパッケージに対する公開権限を持っていることを確認してください。

PR 自動化の競合は、ブランチ保護ルールがボットによるバージョンコミットのプッシュをブロックする場合に発生します。GitHub Actions ボットに保護のバイパスを許可するか、適切な権限を持つ専用のボットアカウントを使用してください。

マルチパッケージの公開順序は、パッケージが相互に依存している場合に重要です。Changesets はこれを自動的に処理しますが、公開途中でのネットワーク障害により、モノレポが不整合な状態になる可能性があります。changesets/action にはリトライロジックが含まれていますが、この障害モードを理解することは復旧に役立ちます。

changeset の追加忘れは、コントリビューターの最も一般的なミスです。Changeset bot は changeset が欠落している PR にコメントしますが、changeset が必要なのに存在しない場合に失敗する CI チェックを追加することもできます。

今日のワークフローの構築

ほとんどのチームは、main へのプッシュごとに Changesets アクションを実行します。このアクションは、未リリースの changeset が存在する場合に「Version Packages」PR を開くか更新し、バージョン PR がマージされたときにパッケージを公開します。

これにより、自然なリリースサイクルが作成されます。週を通じて機能をマージし、出荷する準備ができたらバージョン PR をマージします。手動でのバージョン編集、changelog の更新忘れ、間違ったパッケージの公開はありません。

まとめ

適切に設定された Changesets リリースワークフローは、パッケージリリースの認知的負荷を取り除きます。コントリビューターは事前に意図を宣言し、CI が調整を処理し、npm trusted publishing が安全で検証可能なアーティファクトを保証します。

フローを理解するために単一パッケージのセットアップから始め、必要に応じてモノレポに拡張してください。初期設定への投資は、リリースに対する不安の軽減と「おっと、間違ったバージョン」という瞬間の減少により、すぐに報われます。

よくある質問

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.