Changesetsでnpmへのリリースを自動化する

最近、筆者が管理するいくつかのGitHubリポジトリーにChangesetsを導入しました。これによってnpmへのリリース作業を自動化でき、負担が減りました。この記事では、Changesetsを導入する手順を詳しく解説します。

Changesetsとは

Changesetsは、パッケージのバージョニングやリリースノートの作成、さらにはnpmへの公開までを自動化できるシステムです。Astroやpnpmの開発でも利用されています。

モノリポジトリーにも通常のシングルリポジトリーにも対応しています。また、コミットメッセージの形式についての制約がなく、生成されたリリースノートを編集することもできます。

Changesetsを使った開発は、次のような流れになります。

1. コードに変更を加える
2. npx changesetを実行して変更の規模（major/minor/patch）とその内容を入力する
3. 変更をコミットし、プルリクエストを作成する
4. プルリクエストをマージする
5. Changesetsがバージョン番号の変更やリリースノートが含まれるプルリクエストを自動で作成する
6. 複数の変更をまとめてリリースしたい場合は、1〜4を繰り返す（その間、Changesetsのプルリクエストは自動で更新される）
7. 任意のタイミングでChangesetsのプルリクエストをマージすると、GitHubのリリースページが自動で作成され、パッケージがnpmへ公開される

この記事では、Changesetsを使って次のことを自動化するための設定方法を詳しく説明します。

• パッケージのバージョニング
• リリースノートの作成
• 自動で生成されたリリースノートは必要に応じて手動で編集できます
• GitHubのリリースページの作成
• npmへの公開
• 任意でnpmのprovenance statementsへの対応可

設定方法

ここからは、ChangesetsをGitHubリポジトリーで使うための手順を説明します。

CLIのインストール

まずは、ChangesetsのCLIをインストールします。

npm install -D @changesets/cli

次に、設定ファイルを作成します。changesets initコマンドを実行すると、.changesetディレクトリーと設定ファイルが作成されます。

$ npx changeset init

🦋  Thanks for choosing changesets to help manage your versioning and publishing
🦋
🦋  You should be set up to start using changesets now!
🦋
🦋  info We have added a `.changeset` folder, and a couple of files to help you out:
🦋  info - .changeset/README.md contains information about using changesets
🦋  info - .changeset/config.json is our default config

設定ファイルの編集

デフォルトでは、パッケージの公開設定がrestrictedになっています。一般向けにnpmで公開する場合は、.changeset/config.jsonのaccessをpublicに変更します。

1
{
2
  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
3
  "changelog": "@changesets/cli/changelog",
4
  "commit": false,
5
  "fixed": [],
6
  "linked": [],
7
  "access": "restricted",
8
  "access": "public",
9
  "baseBranch": "main",
10
  "updateInternalDependencies": "patch",
11
  "ignore": []
12
}

また、デフォルトではリリースノートが./CHANGELOG.mdとして生成されます。これが不要な場合は、changelogにfalseを設定します。

1
{
2
  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
3
  "changelog": "@changesets/cli/changelog",
4
  "changelog": false,
5
  "commit": false,
6
  "fixed": [],
7
  "linked": [],
8
  "access": "public",
9
  "baseBranch": "main",
10
  "updateInternalDependencies": "patch",
11
  "ignore": []
12
}

リリースノートの形式をカスタマイズすることも可能です。コミットやプルリクエストのリンク、コントリビューターの情報を含めたい場合は、@changesets/changelog-githubを利用します。<org>にはGitHubのユーザー名、<repo>にはリポジトリー名を指定します。

npm install -D @changesets/changelog-github

1
{
2
  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
3
  "changelog": "@changesets/cli/changelog",
4
  // ``<org>/<repo>``にはGitHubのユーザー名とリポジトリー名を指定
5
  "changelog": ["@changesets/changelog-github", { "repo": "<org>/<repo>" }],
6
  "commit": false,
7
  "fixed": [],
8
  "linked": [],
9
  "access": "public",
10
  "baseBranch": "main",
11
  "updateInternalDependencies": "patch",
12
  "ignore": []
13
}

リリース用のスクリプトの設定

package.jsonに、バージョン番号の変更時やnpmへの公開時に利用するスクリプトを設定します。ci:versionとci:publishは他の名前でも大丈夫ですが、その場合は後述のGitHub Actionsのコードを変更する必要があります。

1
{
2
    // ...色々な設定
3
    "scripts": {
4
        "ci:version": "changeset version",
5
        "ci:publish": "changeset publish"
6
    }
7
}

ビルド処理などが必要な場合は、ci:versionやci:publishに追加します。たとえば、私のリポジトリーでは次のように設定しています。

1
{
2
    // ...色々な設定
3
    "scripts": {
4
        "build": "tsc",
5
        "version": "npm run build && git add .",
6
        "ci:version": "changeset version && npm run version",
7
        "ci:publish": "npm run build && changeset publish"
8
    }
9
}

GitHub Actionsの設定

Changesetsを使ってリリースを自動化するために、GitHub Actionsを利用します。.github/workflows/release.ymlを作成し、次の内容を入力します。このコードは、公式のサンプルからSlack通知を削除したり、依存関係をアップデートしたりしています。

1
name: Release
2

3
on:
4
    push:
5
        branches: [main]
6

7
concurrency: ${{ github.workflow }}-${{ github.ref }}
8

9
jobs:
10
    release:
11
        runs-on: ubuntu-latest
12

13
        strategy:
14
            matrix:
15
                node-version: [24.x]
16

17
        steps:
18
            - uses: actions/checkout@v5
19

20
            - name: Use Node.js ${{ matrix.node-version }}
21
              uses: actions/setup-node@v4
22
              with:
23
                  node-version: ${{ matrix.node-version }}
24

25
            - run: npm ci
26

27
            - name: Create Release Pull Request or Publish to npm
28
              id: changesets
29
              uses: changesets/action@v1
30
              with:
31
                  version: npm run ci:version
32
                  publish: npm run ci:publish
33
              env:
34
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
35
                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

GitHubとnpmの設定

GitHub Actionsによるファイルの更新やプルリクエストの作成を許可するために、権限を変更します。

GitHubのリポジトリーの［Settings］>［Actions］>［General］を開きます。下にスクロールし、［Workflow permissions］を［Read and write permissions］に変更します。また、［Allow GitHub Actions to create and approve pull requests］をオンにします。

設定の変更後は［Save］ボタンをクリックしてください。

次に、リリースを自動化するために、npmのアクセストークンを作成します。npmに移動してプロフィールアイコンをクリックし、メニューから［Access Tokens］を選択します。

［Generate New Token］から［Classic Token］をクリックし、アクセストークンを発行します。

トークン名には分かりやすいものを設定し、種類では［Automation］を選択してください。

トークンが生成されたら、トークンをコピーします。トークンは一度しか表示されないので注意してください。

トークンをコピーしたらGitHubの設定画面に戻り、［Secrets and variables］>［Actions］から［Repository secrets］を作成します。シークレットの名前はNPM_TOKEN、値は先ほどコピーしたトークンを入力してください。

provenance statementsの設定（任意）

必須ではありませんが、npmのprovenance statementsを利用できます。provenance statementsは、npmパッケージの透明性を向上させられる機能です。日本語では「来歴証明」や「来歴情報」といったところでしょうか。

この機能を使うと、パッケージのnpmページにチェックマークのバッジが表示されるようになります。このバッジをクリックすると、パッケージがどのリポジトリーのどのコミットからどのようなシステムでビルドされたかを確認できます。

従来のnpmでは、GitHubで公開されているコードとnpmで公開されているコードが同一であるという保証がありませんでした。もちろん、自分でビルドして、npmで公開されているコードと差分を取れば確認できますが、逆にいえばそうしない限りは確認する手段がありませんでした。provenance statementsを使えば、GitHubのコードとnpmで公開されているコードが同一であることを簡単に証明できます。

この機能を利用するには、package.jsonのpublishConfig.provenanceをtrueを設定します。

1
{
2
    // ...色々な設定
3
    "publishConfig": {
4
        "provenance": true
5
    }
6
}

次に、.github/workflows/release.ymlに、必要なpermissionsを追加します。

1
name: Release
2

3
on:
4
    push:
5
        branches: [main]
6

7
concurrency: ${{ github.workflow }}-${{ github.ref }}
8

9
jobs:
10
    release:
11
        runs-on: ubuntu-latest
12

13
        permissions:
14
            contents: write
15
            id-token: write
16
            pull-requests: write
17

18
        strategy:
19
            matrix:
20
                node-version: [24.x]
21

22
        steps:
23
            - uses: actions/checkout@v5
24

25
            - name: Use Node.js ${{ matrix.node-version }}
26
              uses: actions/setup-node@v4
27
              with:
28
                  node-version: ${{ matrix.node-version }}
29

30
            - run: npm ci
31

32
            - name: Create Release Pull Request or Publish to npm
33
              id: changesets
34
              uses: changesets/action@v1
35
              with:
36
                  version: npm run ci:version
37
                  publish: npm run ci:publish
38
              env:
39
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
40
                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

これで、npmのprovenance statementsを利用できるようになりました。

Botの導入（任意）

Changesetsには公式のBotがあります。このBotはChangesetsの動作に必須ではありませんが、導入するとプルリクエストにChangesetsのデータが含まれているかを確認してくれます。また、Changesetsのデータが含まれていない場合は、リンクから簡単に作成できるようになっています。

このBotはすべてのプルリクエストにメッセージを送信するので、必要なリポジトリーにだけ導入することをオススメします。

プルリクエストを作成する

これで、必要な設定がすべて完了しました。次に、練習を兼ねて、ここまでの変更を含むプルリクエストを作成しましょう。新しいブランチに切り替えます。

git checkout -b add-changesets

ブランチを切り替えたら、changesetコマンドを実行します。まずは、変更の規模をpatch/minor/majorから選択します。ここでの選択は、バージョン番号の変更時に利用されます。たとえば、前回のバージョンからの変更の中で、もっとも大きな変更がminorだった場合、次のバージョンはマイナーバージョンが上がります。

$ npx changeset

🦋  What kind of change is this for async-query? (current version is 2.0.0) ...
> patch
  minor
  major

次に、変更の内容を入力します。変更の内容は、リリースノートに含まれるため、他の開発者が理解できるように簡潔に記述してください。

$ npx changeset
🦋  What kind of change is this for async-query? (current version is 2.0.0) · patch
🦋  Please enter a summary for this change (this will be in the changelogs).
🦋    (submit empty line to open external editor)
🦋  Summary »  ci: add Changesets settings

変更の内容を入力してエンターを押すと、入力内容を確認されます。内容に問題がなければ、yかエンターを押します。

$ npx changeset
🦋  What kind of change is this for async-query? (current version is 2.0.0) · patch
🦋  Please enter a summary for this change (this will be in the changelogs).
🦋    (submit empty line to open external editor)
🦋  Summary · ci: add Changesets settings
🦋
🦋  === Summary of changesets ===
🦋  patch:  async-query
🦋
🦋  Is this your desired changeset? (Y/n) » true

これで、変更内容が記録されました。あとは、変更をコミットしてプルリクエストを作成します。

git add .
git commit -m "ci: add Changesets settings"
git push add-changesets

GitHubのリポジトリーにアクセスし、プルリクエストを作成します。先ほどChangesetsのBotを導入していた場合は、Botからのコメントが付いているはずです。

問題がなければプルリクエストをマージします。少し待つと、チェンジログの更新やバージョン番号の変更が含まれるプルリクエストが作成されます。チェンジログを修正したい場合は、このプルリクエストに対して変更を加えてください。

このプルリクエストを任意のタイミングでマージすると、GitHubのリリースページが自動で作成され、npmへの公開が行われます。お疲れさまでした！

まとめ

この記事では、Changesetsを使ってnpmへのリリースを自動化する手順を解説しました。Changesetsを導入することで、バージョニングやリリースノートの作成、GitHubのリリースページの作成、npmへの公開を自動化できます。

GitHubリポジトリーでの権限の設定やprovenance statementsの設定などまで書かれた記事が見つからなかったので、この記事を書きました。参考になれば幸いです。

参考

• changesets/changesets: 🦋 A way to manage your versioning and changelogs with a focus on monorepos
• changesets/action
• 参考にさせていただいた記事
• • Changesetsで頑張らないリリース（モノレポ対応）
  • 時期を決めて定期的に更新するnpmパッケージをChangesetsで管理する | Web Scratch
• つまづいたときに参考にさせていただいたIssue
• • Add support for publishing with provenance · Issue #1152 · changesets/changesets
  • Changesets GithubAction not creating github releases · Issue #1202 · changesets/changesets
• 設定などを参考にさせていただいたリポジトリー
• • mscharley/dot: A lightweight inversion of control framework for JavaScript and TypeScript
  • cultureamp/kaizen-design-system: Culture Amp's Kaizen Design System :seedling:
  • alvesvaren/zod-to-openai-tool: Easily create tools from zod schemas to use with OpenAI Assistants and Chat Completions, inspired by tRPC
  • expressive-code/expressive-code: A text marking & annotation engine for presenting source code on the web.
  • withastro/astro: The web framework for content-driven websites. ⭐️ Star to support our work!