Node.jsパッケージの公開

このチュートリアルでは、継続的インテグレーション (CI) ワークフローの一部として、Node.js パッケージをレジストリに公開する方法について学びます。

この記事で

概要

本ガイドでは、継続的インテグレーション（CI）テストにパスした後、Node.jsのパッケージをGitHub Packages及びnpmレジストリに公開するワークフローの作成方法を紹介します。

前提条件

ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳しくは、「ワークフローの書き込み」をご覧ください。

Node.js プロジェクト用に CI ワークフローを作る方法については、「Node.js のビルドとテスト」をご覧ください。

また、以下の基本的な理解があれば役立ちます。

  •         [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)

  •         [AUTOTITLE](/actions/learn-github-actions/variables)

  •         [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions)

  •         [AUTOTITLE](/actions/security-guides/automatic-token-authentication)

パッケージの設定について

          `name` ファイル内の `version` および `package.json` フィールドでは、パッケージをレジストリにリンクするためにレジストリで使用される一意識別子を作成します。 
          `description` ファイルに `package.json` フィールドを含めることによって、パッケージのリスト ページの概要を追加できます。 詳細については、npm ドキュメントの「[package.json ファイルの作成](https://docs.npmjs.com/creating-a-package-json-file)」と「[Node.js モジュールの作成](https://docs.npmjs.com/creating-node-js-modules)」を参照してください。

ローカルの .npmrc ファイルが存在し、registry 値が指定されている場合、npm publish コマンドでは .npmrc ファイルに構成されたレジストリが使用されます。 setup-node アクションを使用して、既定のレジストリとスコープを構成するローカルの .npmrc ファイルをランナーに作成できます。 setup-node アクションは、プライベート リポジトリへのアクセスや node パッケージの公開に使われる認証トークンも入力として受け付けます。 詳細については、setup-node をご覧ください。

          `setup-node` アクションを使用して、ランナーにインストールされている Node.js バージョンを指定できます。

          `publishConfig` ファイルに `package.json` フィールドを構成するステップをワークフローに追加する場合は、`setup-node` アクションを使用して registry-url を指定する必要はありませんが、パッケージを公開するレジストリは 1 つに限られます。 詳細については、npm ドキュメントの「[publishConfig](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#publishconfig)」を参照してください。

npmレジストリへのパッケージの公開

新しいリリースを公開するたびに、パッケージを公開するワークフローをトリガーできます。 次の例のプロセスは、type が published のリリース イベントがトリガーされたときに実行されます。 CI テストに合格すると、プロセスによってパッケージが npm レジストリにアップロードされます。 詳しくは、「リポジトリのリリースを管理する」をご覧ください。

ワークフロー中で npm レジストリに対して認証を受けた操作を行うためには、npm の認証トークンをシークレットとして保存しなければなりません。 たとえば、NPM_TOKEN というリポジトリ シークレットを作成します。 詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

既定では、npm で name ファイルの package.json フィールドを使用して、公開されたパッケージの名前を判断します。 グローバルな名前空間に公開する場合は、パッケージ名だけを含める必要があります。 たとえば、my-package という名前のパッケージを https://www.npmjs.com/package/my-package に公開します。

スコープのプレフィックスを含むパッケージを公開している場合は、そのスコープを package.json ファイルの名前に含めます。 たとえば、npm スコープのプレフィックスが "octocat" で、パッケージ名が "hello-world"、name ファイル内の package.json は @octocat/hello-world である必要があります。 npm パッケージでスコープ プレフィックスが使用され、そのパッケージがパブリックである場合は、オプション npm publish --access public を使用する必要があります。 これは、意図せずプライベートパッケージを公開してしまうことを防ぐためにnpmが必要とするオプションです。

この例では、NPM_TOKEN 環境変数に NODE_AUTH_TOKEN シークレットを格納します。 setup-node アクションによって .npmrc ファイルが作成されると、NODE_AUTH_TOKEN 環境変数からトークンが参照されます。

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish 
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

上の例では、setup-node アクションによって、ランナーに次の内容の .npmrc ファイルが作成されます。

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true

資格情報を適切に構成するには、registry-url で https://registry.npmjs.org/ を setup-node に設定する必要があることに注意してください。

GitHub Packagesへのパッケージの公開

新しいリリースを公開するたびに、パッケージを公開するワークフローをトリガーできます。 次の例のプロセスは、type が published のリリース イベントがトリガーされたときに実行されます。 CI テストに合格すると、プロセスによってパッケージが GitHub Packagesにアップロードされます。 詳しくは、「リポジトリのリリースを管理する」をご覧ください。

宛先リポジトリの設定

          `repository` キーを使ってパッケージを GitHub Packages にリンクすることは省略可能です。 
          `repository` ファイルに `package.json` キーを指定しないことを選択した場合、GitHub Packages は、`name` ファイルの `package.json` フィールドで指定した GitHub リポジトリにパッケージを公開します。 たとえば、`@my-org/test` という名前のパッケージは、`my-org/test` GitHub リポジトリに公開されます。 
          `url` キーで指定された `repository` が無効な場合でも、パッケージは公開される可能性があります。しかし、意図したとおりにリポジトリ ソースにリンクされません。

          `repository` ファイルに `package.json` キーを指定すると、そのキーのリポジトリが GitHub Packages の宛先の npm レジストリとして使用されます。 たとえば、以下の `package.json` を公開すると `my-package` という名前のパッケージが `octocat/my-other-repo` GitHub リポジトリに公開されます。 公開されると、リポジトリ ソースのみが更新され、パッケージは宛先リポジトリからアクセス許可を継承しません。

{
  "name": "@octocat/my-package",
  "repository": {
    "type": "git",
    "url": "https://github.com/octocat/my-other-repo.git"
  },
}

宛先リポジトリへの認証

ワークフローの GitHub Packages レジストリに対して認証済み操作を行うために、GITHUB_TOKEN を使用することができます。 ワークフロー内のジョブが開始されるたびに、GITHUB_TOKEN シークレットはそのリポジトリのアクセス トークンに設定されます。 ワークフロー ファイルでこのアクセス トークンにアクセス許可を設定して、contents アクセス許可に対する読み取りアクセスと、packages アクセス許可に対する書き込みアクセスを付与する必要があります。 詳しくは、「ワークフローでの認証に GITHUB_TOKEN を使用する」をご覧ください。

パッケージを別のリポジトリに公開する場合は、宛先リポジトリ内のパッケージに書き込む権限を持つpersonal access token (classic)を使う必要があります。 詳細については、「個人用アクセス トークンを管理する」および「GitHub Actions でのシークレットの使用」を参照してください。

ワークフローの例

この例では、GITHUB_TOKEN 環境変数に NODE_AUTH_TOKEN シークレットを格納します。 setup-node アクションによって .npmrc ファイルが作成されると、NODE_AUTH_TOKEN 環境変数からトークンが参照されます。

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

          `setup-node` アクションにより、ランナーに `.npmrc` ファイルが作成されます。 
          `scope` アクションに対して `setup-node` 入力を使用すると、`.npmrc` ファイルにスコープ プレフィックスが含まれます。 既定では、`setup-node` アクションにより、`.npmrc` ファイルのスコープが、そのワークフロー ファイルを含むアカウントに設定されます。

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true

Yarn を利用したパッケージの公開

パッケージマネージャーのYarnを使う場合、Yarnを使ってパッケージのインストールと公開が行えます。

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

発行中にレジストリで認証を行うには、認証トークンも yarnrc.yml ファイルで定義されていることを確認します。 詳しくは、Yarn のドキュメントの記事「設定」をご覧ください。