CircleCI で npm publish しているなら、今回の更新はかなり実務的です。npm Trusted Publishing（信頼された公開）が CircleCI をサポートしたことで、GitHub でコードを管理しつつ CircleCI から npm に公開しているチームでも、長期保存の npm トークンを置かずに公開できるようになりました。GitHub Changelog では、CircleCI が GitHub Actions と GitLab CI/CD に続く OIDC プロバイダーになったと案内されています。(The GitHub Blog)
結論からいうと、公開フローの安全性は上げやすくなります。ただし、CircleCI 版には「自動 provenance がまだ付かない」「self-hosted runner は対象外」「1パッケージにつき trusted publisher は1つだけ」といった制約もあります。設定は npmjs.com の package settings か npm trust CLI から行えます。(npm ドキュメント)
npm Trusted Publishing の CircleCI 対応で何が変わったのか
今回の変更の本質は、CircleCI を使うチームが publish 専用の NPM_TOKEN を持たなくて済む選択肢が増えた点です。npm の trusted publishing は OIDC で npm と CI/CD を信頼連携させ、npm publish 時に短命な認証を使います。GitHub Changelog でも、CircleCI から公開する maintainer は保存済み資格情報を排除できると説明されています。(The GitHub Blog)
まずは、今回のアップデートを実務視点で整理すると次のとおりです。(The GitHub Blog)
| 項目 | 今回の内容 | 実務での意味 |
|---|---|---|
| 対応CI | CircleCI Cloud が trusted publishing の対象に追加 | GitHub リポジトリを CircleCI でビルド・公開している構成でも OIDC に寄せやすい |
| 認証方式 | NPM_ID_TOKEN に CircleCI の OIDC token を渡して publish | 長期トークンの保管・ローテーション負荷を下げられる |
| 設定方法 | npmjs.com の Trusted publishing か npm trust circleci | GitHub や CircleCI だけで設定は完結しない |
| 対応範囲 | OIDC は publish 操作中心。self-hosted は未対応 | npm ci などは別認証を考える必要がある |
| provenance | GitHub Actions / GitLab は自動生成、CircleCI は未対応 | 証跡を重視するなら publish 経路の選択が重要になる |
要するに、今回の CircleCI 対応は「新しいCIを増やす話」ではなく、「既に CircleCI を使っているチームが、そのまま安全に npm 公開できるようになる話」です。(The GitHub Blog)
GitHub 利用者にとっての実務メリット
特に恩恵が大きいのは、リポジトリは GitHub にあり、CI/CD 標準は CircleCI というチームです。これまでは公開だけ GitHub Actions に寄せるか、CircleCI に publish 用トークンを持たせるかのどちらかになりがちでした。CircleCI が trusted publishing に対応したことで、公開権限を「人や秘密情報」ではなく「許可されたワークフロー」に寄せやすくなります。(The GitHub Blog)
次のようなチームほど、今回の変更の価値を感じやすいはずです。
- GitHub でソース管理しているが、テスト・ビルド・リリースは CircleCI に統一している
- CircleCI Contexts や project 環境変数に
NPM_TOKENを置きたくない - 複数人がリリースに関わるため、公開権限をタグやジョブ条件で絞りたい
- publish のためだけに GitHub Actions を別運用したくない
公開権限を長期トークンからワークフローIDへ移せるのが、trusted publishing のいちばん大きな価値です。セキュリティ面だけでなく、引き継ぎや token ローテーションの運用負荷も下げやすくなります。(npm ドキュメント)
仕組みを短く理解する
仕組みはシンプルです。npm trusted publishing は OIDC で CI/CD と信頼関係を作り、npm CLI は OIDC 環境を検知すると従来のトークンより先にそちらを使います。CircleCI では circleci run oidc get --claims '{"aud": "npm:registry.npmjs.org"}' で audience を指定した token を取得し、それを NPM_ID_TOKEN として npm publish に渡します。npm はその ID token を短命な publish token に交換して公開を実行します。(npm ドキュメント)
ただし、OIDC が効くのは publish 操作です。private dependency の npm ci や npm install に必要な認証までは置き換わりません。private package を取得するジョブでは、読み取り専用トークンを別途使う前提で設計したほうが安全です。(npm ドキュメント)
導入前に確認すること
導入前に見落としやすい前提条件をまとめます。ここを外すと「設定は保存できたのに公開だけ失敗する」になりやすいです。(npm ドキュメント)
| 確認項目 | 必要条件 | 見落としやすい点 |
|---|---|---|
npm publish 実行環境 | npm CLI 11.5.1以上、Node 22.14.0以上 | CircleCI executor image が古いと OIDC publish 自体が使えない |
npm trust CLI 管理 | npm 11.10.0以上、package の write 権限、account-level 2FA、対象 package が registry 上に存在 | brand-new package や権限不足だと CLI で詰まりやすい |
| 対応環境 | GitHub-hosted runners / GitLab.com shared runners / CircleCI cloud | self-hosted runner は未対応 |
| 運用単位 | 1 package に trusted publisher は1つ | GitHub Actions と CircleCI を同時に本番 publish の正規経路にはしにくい |
| OIDC の適用範囲 | publish 時の認証 | npm whoami、install、view、access は別扱い |
npm trust は workspaces を認識しないため、monorepo ではカレントディレクトリの package.json に依存しすぎないほうが安全です。package 名を明示して実行するほうが事故を減らせます。(npm ドキュメント)
CircleCI で設定する手順
npm 側で trusted publisher を登録する
設定の起点は GitHub ではなく npm 側です。npmjs.com で Packages → 対象 package → Settings → Trusted publishing を開き、CircleCI を選んで信頼関係を作ります。変更は将来の publish にすぐ反映されます。(npm ドキュメント)
Web 画面で求められる主な情報は次の5つです。(npm ドキュメント)
- Organization ID
CircleCI Organization Settings の Overview で確認する UUID です。 - Project ID
CircleCI Project Settings の Overview で確認する UUID です。 - Pipeline definition ID
CircleCI Project Setup で確認する UUID です。 - VCS origin
GitHub リポジトリなら、github.com/owner/repoのような origin を指定します。 - Context IDs（任意）
特定 context を使う job だけに publish を制限したいときに使います。
どのIDをどこで確認するかは npm Docs が画面単位で案内しています。実務的には、publish 用の CircleCI context を別に切り出し、その context ID を trusted publisher に登録しておくと、同じ project 内の別 job から不用意に publish されるリスクを下げやすくなります。(npm ドキュメント)
CLI で登録する場合
Web UI ではなく CLI で管理したいなら npm trust circleci が使えます。これは npm website での設定のコマンドライン版で、CircleCI 向けには org / project / pipeline definition / vcs origin を指定します。CLI を使う場合は npm 11.10.0以上、2FA、有効な package 権限が必要です。(npm ドキュメント)
npm trust circleci my-package \
--org-id <circleci-org-uuid> \
--project-id <circleci-project-uuid> \
--pipeline-definition-id <pipeline-definition-uuid> \
--vcs-origin <origin> \
-y既に GitHub Actions など別の trusted publisher を使っている package は、そのまま CircleCI を追加できません。1 package 1設定なので、npm trust list で既存設定を確認し、必要なら npm trust revoke --id <trust-id> で外してから切り替えるか、npmjs.com 側で既存設定を編集します。(npm ドキュメント)
CircleCI の publish ジョブ例
CircleCI 側の publish job は、NPM_TOKEN を埋め込む代わりに、OIDC token を NPM_ID_TOKEN として渡す構成に変わります。公式例の要点だけ残すと、次のように考えると分かりやすいです。(npm ドキュメント)
version: 2.1
jobs:
publish:
docker:
- image: cimg/node:22.14
steps:
- checkout
- run: npm ci
- run: npm test
- run:
name: Publish to npm with OIDC
command: |
export NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud": "npm:registry.npmjs.org"}')
npm publish
workflows:
release:
jobs:
- publish:
filters:
tags:
only: /^v.*/
branches:
ignore: /.*/aud は npm:registry.npmjs.org にする必要があります。また、CircleCI でこの方法で生成した OIDC token はマスクされずに表示され得るので、echo やデバッグ出力に流さない運用が重要です。(npm Registry API)
実運用では、GitHub 側の release tag 作成を publish の入口にすると管理しやすくなります。CircleCI の公式例もタグ実行限定で、branches は無視する形です。GitHub の tag protection と組み合わせると、「誰が公開を開始できるか」まで締めやすくなります。(npm ドキュメント)
既存の NPM_TOKEN 運用から安全に移行する手順
既存の NPM_TOKEN 運用から切り替えるなら、いきなり token を消さず、次の順で進めると事故が少なめです。
- CircleCI executor の Node / npm バージョンを条件以上に上げる
- npm 側で trusted publisher を登録し、CircleCI job を OIDC 版に切り替える
- まずは小さな patch リリースや検証用 package で publish 成功を確認する
- npm の
Publishing accessで token を禁止する設定に切り替える - 使わなくなった automation token を revoke し、CircleCI Contexts / project env vars からも削除する
- GitHub の tag 作成権限を見直し、公開トリガーを release 担当者に絞る
npm Docs も、trusted publisher を先に動作確認してから token を禁止し、不要な automation token を revoke する順を勧めています。追加の安全策として、tag protection や trusted publisher 設定の定期棚卸しも挙げられています。(npm ドキュメント)
CircleCI を選ぶべきケースと、まだ見送るべきケース
すぐ導入しやすいケース
- CI/CD の標準がすでに CircleCI
npm publishのためだけに GitHub Actions を別管理している- CircleCI の context や環境変数から publish token をなくしたい
- release pipeline を1本に揃えたい
まだ見送るべきケース
- npm package に provenance を自動付与したい
- self-hosted runner 前提の運用をしている
npm publish以外の npm 操作まで OIDC 一元化したい- GitHub Actions を正規の release path として既に安定運用している
判断基準はかなり明快です。CircleCI trusted publishing は「CircleCI を使い続けながら token 管理を減らす」には向いていますが、「provenance も今すぐ自動で欲しい」には向きません。現時点で自動 provenance が付くのは GitHub Actions と GitLab CI/CD で、しかも trusted publishing かつ public repository / public package が条件です。private repository では provenance は自動生成されません。(npm ドキュメント)
よくある失敗と対処
最後に、実務で詰まりやすいポイントを先に潰しておきます。公式ドキュメントで明示されているものと、そこから見える典型パターンをまとめると次の通りです。(npm ドキュメント)
| 症状 | よくある原因 | 対処 |
|---|---|---|
ENEEDAUTH / Unable to authenticate | Org / Project / Pipeline / VCS origin などが不一致、または未対応環境 | 各値を厳密に見直し、CircleCI Cloud かどうかも確認する |
| 設定保存後も publish だけ失敗する | npm は trusted publisher 設定を保存時に検証しない | 一字一句見直し、実 publish で検証する |
npm ci が通らない | trusted publishing は publish 専用 | private dependency 取得には read-only token を残す |
| OIDC token がログに出る | token を echo や debug 出力した | circleci run oidc get の結果を表示しない |
npm whoami で確認できない | OIDC 認証は publish 時だけ | 成否確認は publish 実行ログで行う |
| provider 切り替えで混乱する | 1 package 1 trusted publisher | npm trust list / revoke か npmjs.com の編集で切り替える |
npm Trusted Publishing の CircleCI 対応で、GitHub を使う JavaScript / Node.js チームは「CircleCI から安全に npm 公開する」選択肢を正式に持てるようになりました。価値が大きいのは、公開用の長期トークンを減らしつつ、既存の CircleCI release flow を崩さずに済む点です。(The GitHub Blog)
次にやることは3つです。CircleCI executor の Node / npm を条件に合わせる、npm 側で trusted publisher を登録する、publish 成功後に NPM_TOKEN と automation token を撤去する。逆に、provenance の自動生成を最優先するなら、現時点では GitHub Actions で publish を維持する判断も十分合理的です。(npm ドキュメント)
コメント