npm Trusted Publishingでトークンなしに公開する
npmのTrusted Publishingを使うと、GitHub ActionsからOIDCで認証し、トークンなしでパッケージを公開できます。Changesetsとchangesets/actionでの設定と、詰まりどころをまとめます。
はじめに
npmのTrusted Publishingは、GitHub ActionsなどのCIから、OIDCで発行される短い期限の資格情報を使ってパッケージを公開する仕組みです。npmのアクセストークンを発行してCIに置かなくても公開できます。
これまで、CIからの公開は、npmで生成したAccess Tokensを用いて行う必要がありました。 トークンは生成する際に有効期限を設ける必要があり、定期的な更新が面倒でした。
手元のPCから公開するときや、Trusted Publishingが対応していないセルフホストランナーから公開するときは、Trusted Publishingを使えないので、これまでどおりログインやアクセストークンで公開します。対応しているのは、GitHubがホストするランナーのGitHub Actions、GitLab.comの共有ランナーのGitLab CI/CD、CircleCIのクラウドです。これらから公開するなら、最初にnpm側で設定するだけで、トークンを置かずに公開できます。
これを機に、このウェブサイトで利用していたReactのコンポーネントとhooksをnpmパッケージとして公開してみました。 @k8ordo/uiという名前で公開しています。
このパッケージの公開は、ChangesetsとGitHub Actionsを利用して行いました。 この記事ではChangesetsとGitHub Actionsの設定と、設定中に詰まったポイントについて紹介します。GitLab CI/CDとCircleCIについては言及していません。
Changesets
詳しい使い方は公式のREADME.mdやこれを紹介するブログ記事に譲りますが、
Changesetsはバージョンと変更履歴の管理とパッケージの公開を自動化してくれる便利なツールです。
まずは、Changesetsを利用できるようにワークスペースの初期設定を行います。
npx @changesets/cli init.changesetディレクトリが作成され、README.mdとconfig.jsonが生成されます。
{
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "restricted",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}細かい設定の変更はしませんが、GitHub内の変更履歴を更新したいので、config.jsonのchangelogの部分だけ変更します。
{
"changelog": [
"@changesets/changelog-github",
{
"repo": "k35o/ArteOdyssey"
}
]
}これで基本的な準備は完了です。
これ以降は、npx @changesets/cliで変更履歴を追加して、npx @changesets/cli versionで変更履歴の整理とバージョンの更新を行い、npx @changesets/cli publishでパッケージを公開します。
最初に行うnpx @changesets/cliは、実行するとCLIで変更の内容を入力が促されます。完了後、それをまとめたMarkdownファイルが.changesetディレクトリに作成されます。
次に行うnpx @changesets/cli versionは、npx @changesets/cliで追加されたMarkdownが削除され、その内容をまとめたものがCHANGELOG.mdに記述されます。さらに、package.jsonのバージョンも更新されます。
最後に行うnpx @changesets/cli publishは、現在のプロジェクト情報をもとにnpmに公開します。
OIDCに関連する設定はパッケージごとに行う必要があるため、npmにパッケージのページを作成する目的で、ここで一度パッケージを公開しました。
GitHub Actions
GitHub Actionsを利用して、npx @changesets/cli versionとnpx @changesets/cli publishの自動化を行います。
まずは、GitHub上でChangesetsが作業を行えるように、リポジトリにChangesetsのGitHub Appを導入します。
導入が完了したら、changesets/actionを利用したGitHub Actionを記述します。
name: Release
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
permissions:
contents: write
id-token: write
pull-requests: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version-file: 'package.json'
- name: Install latest npm
run: npm install -g npm@latest
- name: Install dependencies
run: npm ci
- name: Create release Pull Request or publish to NPM
uses: changesets/action@v1
with:
publish: npx @changesets/cli publish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}このファイルは.github/workflowsにrelease.ymlという名前で作成しました。
このActionはmainブランチにpushされたときに、Changesetsが.changesetの変更履歴に応じてバージョンアップのPRを作成・更新してくれます。(npx @changesets/cli versionの役割)
さらに、そこで作成されたPRがmainブランチにpushされたタイミングでは、publishに渡したコマンドでnpmパッケージへのリリースを行なってくれます。(npx @changesets/cli publishの役割)publishを渡さないと、PRをマージしても公開されません。
このままではこのActionは失敗します。npmに認証するため方法が提供されていないためです。
OIDCを利用しない場合は、npmで生成したAccess Tokensを環境変数としてNPM_TOKENに追加し、changesets/action@v1のenvにNPM_TOKEN: ${{ secrets.NPM_TOKEN }}のように設定していました。
OIDCを利用する場合は、NPM_TOKENの設定は不要です。
リリースするパッケージのSettingsページを開き、Trusted PublisherでGitHub Actionsを選択します。

GitHub Actionsを選択すると、Trusted Publisherの設定が開始されます。

Workflow filenameには拡張子を含めたファイル名だけを記述することに注意してください。
これで全ての準備が完了です。GitHub Actionsは滞りなく動くことでしょう。
詰まったポイント
ドキュメントに書いてあることも多いですが、いくつかのポイントを紹介します。
うまく動かない場合は以下の点を確認してください。
id-token権限の追加
GitHub Actionsのpermissionsでid-tokenにwrite権限を付与する必要があります。
ドキュメントに大きく書いてありますが、OIDCを利用しないケースでは不要なため、つけ忘れが起きました。
npmのバージョン
npmのバージョンが11.5.1以上で、Node.jsのバージョンが22.14.0以上である必要があります。
pnpmを利用していたので、npmのバージョンに無頓着で、GitHub Actions上では10系を用いていたので動きませんでした。
そのため、npmのバージョンを最新にするstepsを追加しました。
- name: Install latest npm
run: npm install -g npm@latestNode.js 22に同梱されるnpmは10系ですが、Node.js 24.5.0以降に同梱されるnpmは11.5.1以上です。Node.js 24.5.0以降を使うなら、npmを入れ直すこのstepは要りません。
package.jsonのrepositoryフィールドの設定
package.jsonのrepositoryフィールドにtypoがあるとリリースが失敗します。
リポジトリとパッケージがどちらもpublicなら、Trusted Publishingは来歴(provenance)を自動で付けて公開します。そのとき、repository.urlがGitHubのリポジトリと完全に一致している必要があります。
おわりに
今回OIDCによる認証を導入したことで、より安定した開発環境を構築できました。
Trusted Publisherを一度設定すれば、公開のたびにOIDCで短い期限の資格情報が発行されるので、トークンの期限切れを気にする必要がありません。 簡単で安全に設定できるので、今後のパッケージ開発においてはこの認証方式を使用していきたいです。
ただし、リリース用のワークフローのファイル名を変更すると動作しなくなる点は忘れないようにしたいです。
