Skip to main content

npmレジストリの利用

GitHub Packages にパッケージを公開するよう npm を設定し、GitHub Packages に保存されたパッケージを依存関係として npm プロジェクトで利用できます。

GitHub Packages は、GitHub Free、GitHub Pro、Organization の GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0 以降、GitHub AE で利用できます。
GitHub Packagesは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 また、レガシーのリポジトリごとのプランを使っているアカウントは、リポジトリごとに課金される Container registry にはアクセスできません。 詳細については、「GitHub's products」を参照してください。

GitHub Packages への認証を行う

パッケージを発行、インストール、および削除するには、アクセス トークンが必要です。

個人アクセス トークン (PAT) を使用し、GitHub Packages または GitHub API の認証を受けることができます。 個人トークンを作成する際には、必要に応じて様々なスコープをトークンに割り当てできます。 PAT のパッケージ関連のスコープの詳細については、「GitHub パッケージのアクセス許可について」を参照してください。

GitHub Actionsワークフロー内でGitHub Packagesレジストリに認証を受けるには、以下の方法が使えます。

  • GITHUB_TOKEN では、ワークフロー リポジトリに関連付けられているパッケージを発行します。

  • packages:read 以上のスコープが設定された PAT では、(GITHUB_TOKEN ではアクセスできない) 他のプライベート リポジトリに関連付けられているパッケージがインストールされます。

    お使いのワークフローで個人アクセス トークン (PAT) を使用してレジストリの認証を受ける場合、GITHUB_TOKEN を使用するようにワークフローを更新することを強くお勧めします。

個人用アクセス トークンでレジストリの認証を行うワークフローの更新についてのガイダンスは、「PAT を使ってレジストリにアクセスするワークフローをアップグレードする」をご覧ください。

GITHUB_TOKEN の詳細については「ワークフローで認証する」を参照してください。

アクションでレジストリを使用するときのベスト プラクティスについて詳しくは「GitHub Actions のセキュリティ強化」をご覧ください。

また、Codespaces と GitHub Actions に対して、パッケージにアクセス許可を個別に付与することもできます。 詳しくは、「パッケージへの Codespaces のアクセスの確保」と、「パッケージへのワークフロー アクセスの確認」をご覧ください。

個人アクセストークンでの認証

GitHub Packages内でパッケージを公開及びインストールするためには、適切なスコープで個人アクセストークンを使わなければなりません。 詳しくは、「GitHub Packages について」をご覧ください。

ユーザーごとの ~/.npmrc ファイルを編集して個人用アクセス トークンを含めるか、コマンド ラインでユーザー名と個人用アクセス トークンを使用して npm にログインすることによって、npm で GitHub Packages に対して認証を行うことができます。

~/.npmrc ファイルに個人用アクセス トークンを追加して認証を行うには、プロジェクトの ~/.npmrc ファイルを編集して次の行を含めます。TOKEN は個人用アクセス トークンに置き換えます。 存在しない場合は、新しい ~/.npmrc ファイルを作成します。

//npm.pkg.github.com/:_authToken=TOKEN

npm にログインして認証を行うには、npm login コマンドを使用します。USERNAME は GitHub ユーザー名に、TOKEN は個人用アクセス トークンに、PUBLIC-EMAIL-ADDRESS はメール アドレスに置き換えます。

GitHub Packages が npm を使用するための既定のパッケージ レジストリではなく、npm audit コマンドを使用する場合は、GitHub Packages に対する認証時に、パッケージの所有者と共に --scope フラグを使用することをお勧めします。

$ npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

パッケージの公開

注: パッケージ名とスコープには小文字のみを使用する必要があります。

GitHub Packages レジストリは、Organization 内または個人アカウント内に npm パッケージを格納し、パッケージをリポジトリに関連付けることができます。 権限をリポジトリから継承するか、リポジトリとは別に細かい権限を設定するかを選ぶことができます。

既定では、GitHub Packages は package.json ファイルの name フィールドで指定された GitHub リポジトリにパッケージを公開します。 たとえば、@my-org/test という名前のパッケージは、my-org/test GitHub リポジトリに公開することになります。 npm v8.5.3 以降を実行している場合は、パッケージ ディレクトリに README.md ファイルを含めることで、パッケージのリスト ページの概要を追加できます。 詳しくは、package.json の利用Node.js モジュールの作成方法に関する npm のドキュメントをご覧ください。

URL フィールドを package.json ファイルに含めることで、同じ GitHub リポジトリに複数のパッケージを公開できます。 詳しくは、「同じリポジトリへの複数パッケージの公開」をご覧ください。

パッケージが公開されても、リポジトリに自動的にリンクされることはありません。 ただし、ユーザー インターフェイスまたはコマンド ラインを使用して、公開済みのパッケージをリポジトリにリンクすることはできます。 詳細については、「リポジトリのパッケージへの接続」を参照してください。

プロジェクト内にあるローカルの .npmrc ファイルか、package.jsonpublishConfig オプションを使用して、プロジェクトのスコープのマッピングを設定できます。 GitHub Packagesはスコープ付きのnpmパッケージのみをサポートしています。 スコープ付きのパッケージには、@owner/name 形式の名前が付いています。 スコープ付きのパッケージの先頭には常に @ 記号が付いています。 スコープ付きの名前を使うには、package.json で名前を更新する必要がある場合があります。 たとえば、"name": "@codertocat/hello-world-npm" のようにします。

パッケージを最初に公開する場合、既定の可視性はプライベートです。 パッケージがリポジトリにリンクされている場合、パッケージの可視性はリポジトリの可視性に依存します。 可視性を変更したりアクセス権限を設定するには、「パッケージのアクセス制御と可視性の設定」を参照してください。

パッケージを公開した後は、GitHub上でそのパッケージを見ることができます。 詳しくは、「パッケージの表示」をご覧ください。

ローカルの .npmrc ファイルを使用したパッケージの公開

.npmrc ファイルを使用して、プロジェクトのスコープのマッピングを設定できます。 .npmrc ファイルで GitHub Packages の URL とアカウント所有者を使い、GitHub Packages がパッケージ要求のルーティング先を把握できるようにしてください。 .npmrc ファイルを使うことで、他の開発者がパッケージを GitHub Packages ではなく npmjs.org に誤って公開することを防止できます。

  1. GitHub Packagesに認証を受けてください。 詳細については、「GitHub Packages への認証」を参照してください。 2. package.json ファイルと同じディレクトリで、.npmrc ファイルを作成するか編集し、GitHub Packages URL とアカウント所有者を指定する行を含めます。 OWNER を、プロジェクトを含むリポジトリを所有しているユーザーもしくは組織アカウント名で置換します。

    @OWNER:registry=https://npm.pkg.github.com
  2. GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。 詳細については、「リポジトリにファイルを追加する」を参照してください。

  3. プロジェクトの package.json にあるパッケージの名前を確認します。 name フィールドには、スコープとパッケージの名前が含まれている必要があります。 たとえば、パッケージの名前が "test" で、"My-org" GitHub Organization に公開する場合、package.jsonname フィールドは @my-org/test にする必要があります。

  4. プロジェクトの package.jsonrepository フィールドを確認します。 repository フィールドは、GitHub リポジトリの URL と一致している必要があります。 たとえば、リポジトリの URL が github.com/my-org/test である場合、repository フィールドは https://github.com/my-org/test.git でなければなりません。 1. パッケージを公開してください。

    $ npm publish

package.json ファイルでの publishConfig を使用したパッケージの公開

package.json ファイルで publishConfig 要素を使用して、パッケージを公開するレジストリを指定できます。 詳細については、npm ドキュメントの「publishConfig」を参照してください。

  1. パッケージの package.json ファイルを編集して、publishConfig のエントリを含めるようにします。

    "publishConfig": {
      "registry":"https://npm.pkg.github.com"
    },
    1. プロジェクトの package.jsonrepository フィールドを確認します。 repository フィールドは、GitHub リポジトリの URL と一致している必要があります。 たとえば、リポジトリの URL が github.com/my-org/test である場合、repository フィールドは https://github.com/my-org/test.git でなければなりません。 1. パッケージを公開してください。
    $ npm publish

同じリポジトリへの複数パッケージの公開

複数のパッケージを同じリポジトリに公開する場合は、GitHub リポジトリの URL を、各パッケージの package.json ファイルの repository フィールドに含めます。

リポジトリのURLが正しいことを確認するには、REPOSITORYを公開したいパッケージを含むリポジトリ名で、OWNERをリポジトリを所有しているGitHubのユーザもしくはOrganizationアカウント名で置き換えてください。

GitHub Packages は、パッケージ名の代わりに、このURLを元にしてリポジトリを照合します。

"repository":"https://github.com/OWNER/REPOSITORY",

パッケージのインストール

プロジェクトの package.json ファイルに依存関係としてパッケージを追加することで、GitHub Packages からパッケージをインストールできます。 プロジェクトで package.json を使用する方法について詳しくは、package.json の利用に関する npm のドキュメントをご覧ください。

デフォルトでは、パッケージは1つのOrganizationから追加できます。 詳しくは、「他の Organization からのパッケージのインストール」をご覧ください。

プロジェクトに .npmrc ファイルを追加して、パッケージをインストールするためのすべての要求が GitHub Packages を経由するようにする必要もあります。 すべてのパッケージ要求を GitHub Packages 経由になるようにルーティングすると、npmjs.org のスコープ付きおよびスコープなしのパッケージをどちらも使用できるようになります。詳しくは、npm のスコープに関する npm のドキュメントをご覧ください。

  1. GitHub Packagesに認証を受けてください。 詳細については、「GitHub Packages への認証」を参照してください。 2. package.json ファイルと同じディレクトリで、.npmrc ファイルを作成するか編集し、GitHub Packages URL とアカウント所有者を指定する行を含めます。 OWNER を、プロジェクトを含むリポジトリを所有しているユーザーもしくは組織アカウント名で置換します。

    @OWNER:registry=https://npm.pkg.github.com
  2. GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。 詳細については、「リポジトリにファイルを追加する」を参照してください。

  3. インストールするパッケージを使用するように、プロジェクトの package.json を構成します。 GitHub Packages のためにパッケージの依存関係を package.json ファイルに追加するには、@my-org/server のように完全なスコープ付きのパッケージ名を指定してください。 npmjs.com のパッケージの場合は、@babel/core または @lodash のように完全な名前を指定してください。 たとえば、次の package.json では、依存関係として @octo-org/octo-app パッケージが使用されます。

    {
      "name": "@my-org/server",
      "version": "1.0.0",
      "description": "Server app that uses the @octo-org/octo-app package",
      "main": "index.js",
      "author": "",
      "license": "MIT",
      "dependencies": {
        "@octo-org/octo-app": "1.0.0"
      }
    }
    
  4. パッケージをインストールします。

    $ npm install

他のOrganizationからのパッケージのインストール

デフォルトでは、1つのOrganizationからのみGitHub Packagesパッケージを利用できます。 パッケージ要求を複数の Organization とユーザーにルーティングする場合は、 .npmrc ファイルに行を追加できます。OWNER はプロジェクトが含まれているリポジトリを所有するユーザーまたは Organization アカウントの名前に置き換えます。

@OWNER:registry=https://npm.pkg.github.com
@OWNER:registry=https://npm.pkg.github.com