npm stage-onlyトークン：配信自動化と最終承認を切り分ける際に残すべき証拠
CIがパッケージを作成する権限とそのパッケージをユーザーに公開する権限を分離することで、リリースの最終的な責任の所在がより明確になります。しかし、承認ボタンを1つ追加しただけでサプライチェーンのリスクが消えるわけではありません。承認者が何を確認するのかを定めることから始める必要があります。
GitHubは9月18日、npm granular access tokenにおいてstage-onlyの書き込み権限を選択可能になったと発表しました。自動化プロセスがバージョンを審査待ち状態として送信し、メンテナーが2FAによって公開を承認するフローです。以下では、公式の変更内容と、それを運用に組み込むための編集部の提案を区別して説明します。
直接公開の遮断と書き込み権限の完全な剥奪は異なります
公式の案内に基づくと、該当のトークンでnpm stage publishを実行することはできますが、npm publishによる直接公開は拒絶されます。自動化のための2FAバイパス設定が存在する場合でも、この制限は適用されます。既存トークンの動作が自動的に変更される機能ではなく、選択的に導入するものです。
注意すべき点は、dist-tagの移動やバージョンの非推奨化（deprecation）といった他のパッケージ書き込み権限は残るということです。stage-onlyという名称を、読み取り専用や無害なトークンであると解釈してはなりません。許可するパッケージのスコープ、シークレットの保管場所、利用主体、廃棄手順は引き続き管理する必要があります。
承認者が照合するリリースバンドルを定めます
以下に述べる内容は、npmによる必須設定ではなく、小規模チーム向けの運用上の提案です。1回の承認リクエストにつき、ソースコミット、対象パッケージとバージョン、テスト結果、パッケージに含まれるファイル一覧、変更の要約をセットで残してください。承認者がCIログのあちこちから証拠をつなぎ合わせなければならない場合、レビューは形式的なクリックになりがちです。
特に、ソースコードのレビューと配布ファイルのレビューは別物です。リポジトリには存在しなかったファイルがビルドプロセスで紛れ込むこともあれば、必要なファイルが欠落することもあります。チームは実際に提出する成果物を基準にレビュー資料を作成し、レビュー後に成果物を変更した場合は新たなレビュー対象として扱う、という原則を設けることができます。
グリーンCIの後にも保留状態が存在します
これまでの自動化でコマンドの成功をリリースの完了として報告していたなら、ステータスの表現から改める必要があります。提出完了、承認待ち、公開完了を区分し、それぞれの確認根拠を記録する方式です。通知には「成功」という一言だけを出すよりも、現在のフェーズと担当者を記載する方が運用者にとって有用です。
架空の例として、夜間のCIが新バージョンを提出したものの、担当者が翌日にレビューする場合、提出の時点でエンドユーザー向けのリリース告知を出してはいけません。チームが定めた公開確認が済んだ後にドキュメント更新や告知へ進むよう連携させてください。キューが滞留した際に誰がレビューし、過去の提出をいつクリーンアップするかも事前に合意しておくべきです。
1つの小さなパッケージで移行を検証します
現行の公式案内における前提条件には、既存のnpmパッケージ、パッケージの公開権限、アカウントの2FA、npm CLI 11.15.0以上、およびNode.js 22.14.0以上が含まれます。実際の移行前には最新のドキュメントを再確認し、使用しているrunnerのバージョンを点検してください。
まずは影響の小さいパッケージ1つでトークンのスコープを限定し、stagingへの提出、メンテナーによるレビュー、公開結果の確認までを演習することをお勧めします。失敗した際に即座に広範な権限を持つ既存トークンへフォールバックさせてしまうと、せっかく分離した境界が無意味になります。承認の遅延も正常な状態の1つとして処理できなければなりません。
trusted publishingと比較すべき問い
npmはOIDCを利用したtrusted publishingも提供しています。サポートされているCI環境やチームの承認方式に適しているかどうかを見定めることが先決であり、stage-onlyトークンを全チームの決定的な解決策として一般化する理由はありません。トークンを使い続ける必要がある自動化にとって、段階的に移行するための選択肢が1つ増えたと捉えることができます。
公式発表では、2027年1月を目標としてbypass-2FAトークンによる直接公開を廃止する方針が示されています。確定したすべての実装詳細を推測するよりも、対象ワークフローのリストアップと移行担当者の選定を今進める方が現実的です。日程の変更有無については、今後の公式アナウンスを確認する必要があります。
導入の是非を判断するにあたって
本記事はコミュニティの広範な合意や、実際のインシデント減少率を主張するものではありません。新機能の公式な動作を前提に、検証可能な運用手順を提案したものです。自動化に委ねる役割と人間が確認すべき作業が何であるかを説明できるかどうかが、導入判断の出発点となります。
今日から着手できる作業は、現在リリーストークンを使用している箇所を洗い出し、公開完了を判定する条件を明文化し、1回の承認に必要とされる証拠を規定することです。権限の制限とレビュー品質の双方に向き合ってこそ、stagingフェーズが真に役立ちます。