k8o

はじめに

npmパッケージを公開するにあたり、GitHub ActionsまたはGitLab CI/CD PipelinesではOIDCを利用した認証が可能になりました。

これまで、これらのCI・CDからの公開は、npmで生成したAccess Tokensを用いて行う必要がありました。 トークンは生成する際に有効期限を設ける必要があり、定期的な更新が面倒でした。

OIDCを利用した公開に切り替えると最初にnpm側の設定を行うだけで、トークンの交換を考えずに開発を行えるようになります。

これを機に、このウェブサイトで利用していたReactのコンポーネントとhooksをnpmパッケージとして公開してみました。 @k8o/arte-odysseyという名前で公開していますので興味があれば覗いてみてください（このサイトから剥がしただけで使いやすい状況になっていません。今後使いやすい形にしていく予定です）。

このパッケージの公開は、ChangesetsとGitHub Actionsを利用して行いました。 この記事ではChangesetsとGitHub Actionsの設定と、設定中に詰まったポイントについて紹介します。GitLabでもOIDCを利用したパッケージの公開ができますが、GitLabについては言及していません。

Changesets

詳しい使い方は公式のREADME.mdやこれを紹介するブログ記事に譲りますが、 Changesetsはバージョンと変更履歴の管理とパッケージの公開を自動化してくれる便利なツールです。

まずは、Changesetsを利用できるようにワークスペースの初期設定を行います。

npx @changesets/cli init

.changesetディレクトリが作成され、README.mdとconfig.jsonが生成されます。

{
  "$schema": "https://unpkg.com/@changesets/[email protected]/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
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

このファイルは.github/workflowsにrelease.ymlという名前で作成しました。

このActionはmainブランチにpushされたときに、Changesetsが.changesetの変更履歴に応じてバージョンアップのPRを作成・更新してくれます。（npx @changesets/cli versionの役割） さらに、そこで作成されたPRがmainブランチにpushされたタイミングではnpmパッケージへのリリースを行なってくれます。（npx @changesets/cli publishの役割）

このままではこの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-tokensにwrite権限を付与する必要があります。

ドキュメントに大きく書いてありますが、OIDCを利用しないケースでは不要なため、つけ忘れが起きました。

npmのバージョン

npmのバージョンが11.5.1以上である必要があります。 pnpmを利用していたので、npmのバージョンに無頓着で、GitHub Actions上では10系を用いていたので動きませんでした。

そのため、npmのバージョンを最新にするstepsを追加しました。

- name: Install latest npm
  run: npm install -g npm@latest

npmのバージョンを上げるより良い方法がありそうな気がしているので、あればコメントやIssueなどで教えていただきたいです。

package.jsonのrepositoryフィールドの設定

package.jsonのrepositoryフィールドにtypoがあるとリリースが失敗します。

これは、OIDCを利用しなくても失敗するかもしれませんが、念の為記述しました。

おわりに

今回OIDCによる認証を導入したことで、より安定した開発環境を構築できました。

OIDCは一度設定してしまえばほぼ永続的に認証が維持されるため、期限切れを気にする必要がありません。 簡単で安全に設定できるので、今後のパッケージ開発においてはこの認証方式を使用していきたいです。

ただし、リリース用のワークファイル名を変更すると動作しなくなる点は忘れないようにしたいです。