Node.jsパッケージの公開

はじめに

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

必要な環境

ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳しい情報については、「GitHub Actions を学ぶ」を参照してください。

Node.jsプロジェクトのためのCIワークフローの作成に関する詳しい情報については「GitHub ActionsでのNode.jsの利用」を参照してください。

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

• 「npm レジストリの利用」
• 「環境変数」
• 「暗号化されたシークレット」
• 「ワークフローでの認証」

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

package.jsonファイル中のname及びversionフィールドは、レジストリがパッケージをレジストリにリンクするために利用するユニークな識別子を作成します。 package.jsonファイル中にdescriptionを含めることによって、パッケージのリストページのためのまとめを追加できます。 詳しい情報については、npmのドキュメンテーション中の「package.jsonファイルの作成」及び「Node.jsモジュールの作成」を参照してください。

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

setup-nodeアクションを使えば、ランナーにインストールされたNode.jsのバージョンを指定できます。

package.jsonファイルにpublishConfigフィールドを設定するステップをワークフローに追加したなら、setup-nodeアクションを使ってregistry-urlを指定する必要はありませんが、パッケージを公開するレジストリは1つだけに限られます。 詳しい情報についてはnpmドキュメンテーションの「Configの公開」を参照してください。

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

新しいリリースを作成するたびに、パッケージを公開するワークフローを起動できます。 以下の例でのワークフローは、createdという種類でreleaseイベントが発生したときに実行されます。 このワークフローは、CIテストをパスすればnpmレジストリにパッケージを公開します。

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

デフォルトでは、npmはpackage.jsonファイルのnameフィールドを使ってnpmレジストリを決めます。 グローバルな名前空間に公開する場合は、パッケージ名だけを含める必要があります。 たとえばhttps://www.npmjs.com/package/npm-hello-world-testにnpm-hello-world-testという名前のパッケージを公開できます。

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

以下の例は、NPM_TOKENシークレットを環境変数のNODE_AUTH_TOKENに保存します。 setup-nodeアクションが.npmrcファイルを作成する際には、環境変数のNODE_AUTH_TOKENからトークンを参照します。

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # npm に公開するように .npmrc ファイルを設定する
      - uses: actions/setup-node@v2
        with:
          node-version: '12.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      - 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

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

新しいリリースを作成するたびに、パッケージを公開するワークフローを起動できます。 以下の例でのワークフローは、createdという種類でreleaseイベントが発生したときに実行されます。 このワークフローは、CIテストをパスすればGitHub Packagesにパッケージを公開します。

宛先リポジトリの設定

package.json ファイルで repository キーを指定しない場合、GitHub Packages は package.json ファイルの name フィールドで指定した GitHub リポジトリにパッケージを公開します。 たとえば、@my-org/test という名前のパッケージは、my-org/test GitHub というリポジトリに公開されます。

ただし、repository キーを指定すると、そのキーのリポジトリが GitHub Packages の宛先 npm レジストリとして使用されます。 たとえば、以下の package.json を公開すると、my-amazing-package という名前のパッケージが octocat/my-other-repo GitHub リポジトリに公開されます。

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

宛先リポジトリへの認証

ワークフロー中でGitHub Packagesレジストリに対して認証を受けた操作をするには、GITHUB_TOKENが使えます。 ワークフロー内のジョブが開始されるたびに、GITHUB_TOKENはそのリポジトリのアクセストークンに設定されます。 これは、ワークフローが実行されるリポジトリ内でパッケージに対する読み取り及び書き込み権限を持っています。 詳しい情報については「GITHUB_TOKENでの認証を参照してください。

パッケージを別のリポジトリに公開する場合は、宛先リポジトリ内のパッケージに書き込む権限を持つ個人アクセストークン (PAT) を使用する必要があります。 詳しい情報については、「個人アクセストークンを作成する」および「暗号化されたシークレット」を参照してください。

ワークフローの例

以下の例は、GITHUB_TOKENシークレットを環境変数のNODE_AUTH_TOKENに保存します。 setup-nodeアクションが.npmrcファイルを作成する際には、環境変数のNODE_AUTH_TOKENからトークンを参照します。

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          node-version: '12.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

setup-nodeアクションは、ランナー上で.npmrcファイルを作成します。 setup-nodeアクションでscopeインプットを使うと、.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を使ってパッケージのインストールと公開が行えます。

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # npm に公開するように .npmrc ファイルを設定する
      - uses: actions/setup-node@v2
        with:
          node-version: '12.x'
          registry-url: 'https://registry.npmjs.org'
          # 既定値はワークフローファイルを所有するユーザまたは Organization
          scope: '@octocat'
      - run: yarn
      - run: yarn publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

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

setup-nodeアクションをそれぞれのレジストリに対して利用すれば、npmレジストリとGitHub Packagesの両方にパッケージを公開できます。

両方のレジストリにパッケージを公開するなら、npm上のスコーププレフィックスがGitHubのユーザ名もしくはOrganization名と一致することを確認する必要があります。 パッケージをスコーププレフィックス付きでパブリックなレジストリに公開するには、npm publish --access publicコマンドが使えます。 詳しい情報については、npmドキュメンテーション中のnpm-scope及び「スコープ付きのパブリックパッケージの作成と公開」を参照してください。

package.jsonファイルにGitHubレジストリとnpmレジストリのスコープが含まれていることを確かめてください。 たとえば、octocat/npm-hello-world-testリポジトリ内のパッケージをGitHub及びhttps://www.npmjs.com/package/@octocat/npm-hello-world-testに公開する計画をしているなら、*package.json*ファイル内の名前は`"name": "@octocat/npm-hello-world-test"`となるでしょう。

ワークフロー中でGitHub Packagesレジストリに対して認証を受けた操作をするには、GITHUB_TOKENが使えます。 ワークフロー内のジョブが開始されるたびに、GITHUB_TOKENはそのリポジトリのアクセストークンに設定されます。 これは、ワークフローが実行されるリポジトリ内でパッケージに対する読み取り及び書き込み権限を持っています。 詳しい情報については「GITHUB_TOKENでの認証を参照してください。

setup-nodeアクションでscopeインプットを使うと、このアクションはスコーププレフィックスを含む.npmrcファイルを作成します。 デフォルトでは、setup-nodeアクションは.npmrcファイル中のスコープを、ワークフローファイルを所有するユーザもしくはOrganizationに設定します。

このワークフローは、setup-nodeアクションを2回呼びます。 setup-nodeアクションは、実行されるたびに.npmrcファイルを上書きします。 .npmrcファイルは、パッケージレジストリに対する認証を受けた操作を行えるようにしてくれるトークンを、環境変数のNODE_AUTH_TOKENから参照します。 このワークフローは、環境変数のNODE_AUTH_TOKENをnpm publishコマンドが実行されるたびに設定します。初回はnpmへの公開のためのトークン（NPM_TOKEN）が、続いてGitHub Packagesへの公開のためのトークン（GITHUB_TOKEN）が使われます。

name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v2
        with:
          node-version: '10.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      # Publish to npm
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      # Publish to GitHub Packages
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}