npmパッケージの公開をOIDCへ移したのに、リリース後のタグ更新だけアクセストークンが残っている。このような構成を見直せるのが、2026年9月30日に発表されたdist-tag操作への対応です。

ただ、トークンを消す前に考えたいことがあります。新しいバージョンを公開する権限と、利用者が受け取るバージョンを切り替える権限は、同じ役割なのでしょうか。

latestへの昇格を例に、タグ操作の意味と、CIへ与える許可の境界を整理していきましょう。

latestを動かすと、公開済みのどの版を届けるかが変わる

dist-tagは、パッケージのバージョンに付ける名前です。通常、バージョンやタグを指定しないnpm install <package>はlatestを参照します。nextやbetaも配布先の名前として使えますが、latest以外にnpm自身が特別な意味を与えているわけではありません。npm dist-tagの仕様で、この対応関係を確認できます。

たとえば、あるパッケージのlatestが2.0.0、nextが公開済みの2.1.0を指しているとします。検証後にlatestも2.1.0へ向ければ、同じ版を通常の配布先へ昇格できます。これはタグの参照先の変更なので、パッケージを再公開する操作とは分けて考えられます。

ここが、今回の権限を考える出発点ですね。タグを変更できるCIは、新しい版を作らなくても配布先を切り替えられます。昇格を担当するワークフローには便利な一方、その実行条件もリリース手順の一部として扱いたいところです。

dist-tagの許可は、直接公開の許可から独立している

これまでのtrusted publishingは公開とステージングに対応していましたが、dist-tag操作は対象外でした。今回追加されたAllow npm dist-tagを有効にすると、タグ管理にも短命なOIDC資格情報を使えます。新規・既存どちらの設定でも既定値は無効で、従来のトークンによるタグ操作は引き続き利用できます。GitHubの発表

この許可は直接公開とは独立しています。つまり、直接のnpm publishを許可せず、ステージングとタグ管理を許可する組み合わせも可能です。「公開できないから配布先も変えられない」とは限らない、と分かります。

OIDCは、実行中のワークフローの情報を含むトークンを提示し、受け手が信頼条件と照合する仕組みです。長期シークレットの保管を減らせても、どのワークフローを信頼するかという設計は残ります。GitHubのOIDC解説は、この認証と認可の流れを示しています。

複数の設定がある場合は、照合の仕方にも注意が必要です。受け取ったOIDCトークンが、dist-tagを許可した設定のどれか一つに一致すれば操作は認可されます。そのため、設定が重複して一致する構成では、一方を無効にするだけで操作を禁止できるとは限りません。昇格用ワークフローが一致し得る設定を一緒に見直す必要があります。

対応CLIをそろえ、タグの変更前後を確かめる

権限設定に加え、CIで動くCLIも条件を満たす必要があります。npmのtrusted publishingガイドは、dist-tagのOIDC対応として11系では11.21.0以降、12系では12.2.0以降を挙げています。npm CLI 12.2.0のリリースノートにも、この機能の追加が記載されています。

既存のOIDC公開が動いているだけでは、新しいタグ操作にも対応しているとは判断できません。まずCI内でnpm --versionを調べ、パッケージのtrusted publishing設定で対象のAllow npm dist-tagを有効にします。

次は、OIDC設定済みのワークフロー内で行う昇格の例です。example-packageと2.1.0は説明用なので、管理するパッケージ名と公開済みの版へ置き換えます。中央のコマンドは実際にレジストリのタグを書き換えます。

# 現在の参照先を確認する
npm dist-tag ls example-package

# 検証済みの公開バージョンを通常の配布先へ昇格する
npm dist-tag add [email protected] latest

# latestが意図した版を指しているか確認する
npm dist-tag ls example-package

構文はnpm dist-tagの仕様に基づきます。ただし、公開パッケージのタグは認証なしでも読めるため、一覧取得の成功だけでは書き込み権限の検証になりません。非公開パッケージのタグをtrusted publishingで読む場合は、dist-tagの許可が必要です。認証条件の説明に沿って、意図した操作の結果まで確かめましょう。

タグ更新用トークンを外す前に、残る用途を切り分ける

移行の到達点は、タグ更新にだけ必要だった長期資格情報を手放せることです。既存トークンの動作は変わらないので、対象のタグ操作をOIDCで検証してから、不要になった資格情報を失効させる順序で進められます。

一方、非公開依存パッケージのインストールなど、別の処理がトークンを使っている場合は用途が残ります。npmの移行・認証ガイドも、OIDCの動作確認後に不要なトークンを失効させる手順と、非公開依存の読み取り認証を分けて扱っています。

公開と昇格を分けて考えると、必要な許可をどこへ置くかがはっきりします。昇格を担うワークフローにdist-tag権限を与え、その実行条件と変更結果を確かめる。そのうえでタグ更新専用のトークンを外せば、配布先を選ぶ責任を明確にしながら、管理する資格情報を減らせます。

出典

• Title: Opt-in dist-tag permissions for npm trusted publishing
• URL: https://github.blog/changelog/2026-09-30-opt-in-dist-tag-permissions-for-npm-trusted-publishing