Node.jsパッケージの公開

はじめに

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

前提条件

ワークフローの設定オプションと、ワークフローファイルの作成方法についての基本的な知識を持っておくことをおすすめします。 詳細については、「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 ドキュメントの「publishConfig」を参照してく� さい。

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

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

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

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

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

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

name: Publish Package to npmjs
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: '16.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

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

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

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

宛先リポジトリの設定

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

package.json に 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 シークレットはそのリポジトリのアクセス トークンに設定されます。 ワークフロー ファイルでこのアクセス トークンにアクセス許可を設定して、contents スコープに対する読み取りアクセス権と、packages スコープに対する書き込みアクセス権を付与する必要があります。 詳細については、「GITHUB_TOKEN を使用した認証」を参照してく� さい。

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

ワークフローの例

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

name: Publish package to GitHub Packages
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    permissions: 
      contents: read
      packages: write 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          node-version: '16.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 ファイルが作成されます。 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: Publish Package to npmjs
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: '16.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}