npmレジストリの利用

GitHub Packages への認証を行う

非公開パッケージ、内部パッケージ、公開パッケージを発行、インストール、削除するには、アクセス トークンが必要です。

personal access token (classic) を使って、GitHub Packages または GitHub API の認証を受けることができます。 personal access token (classic) を作成するときは、必要に応じてさまざまなスコープをトークンに割り当てることができます。 personal access token (classic) のパッケージ関連のスコープの詳細については、「GitHub Packagesの権限について」を参照してください。

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

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

GitHub Actions ワークフローにおける認証

このレジストリでは、詳細なアクセス許可がサポートされています。 細かなアクセス許可をサポートするレジストリについては、GitHub Actions ワークフローで personal access token を使ってレジストリの認証を受ける場合は GITHUB_TOKEN を使うようにワークフローを更新することを強くお勧めします。 personal access token を使ってレジストリに対する認証を行うワークフローの更新に関するガイダンスについては、「GitHub Actionsでのパッケージの公開とインストール」をご覧ください。

トークンにパッケージに対する admin アクセス許可がある場合、GitHub Actions ワークフローで GITHUB_TOKEN を使用し、REST API を使ってパッケージを削除または復元できます。 ワークフローを使ってパッケージを発行するリポジトリと、パッケージに明示的に接続したリポジトリには、リポジトリ内のパッケージに対する admin アクセス許可が自動的に付与されます。

GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。 アクションでレジストリを使うときのベスト プラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

また、GitHub Codespaces と GitHub Actions に対して、パッケージにアクセス許可を個別に付与することもできます。 詳細については、「パッケージのアクセス制御と可視性の設定」および「パッケージのアクセス制御と可視性の設定」を参照してください。

personal access token

で認証を行う

GitHub Packages でパッケージを発行およびインストールするには、適切なスコープで personal access token (classic) を使う必要があります。 詳しくは、「GitHub Packages の概要」を参照してください。

npm で GitHub Packages に対して認証を行うには、ユーザーごとの ~/.npmrc ファイルを編集して personal access token (classic) を含めるか、コマンド ラインでユーザー名と personal access token を使って npm にログインします。

~/.npmrc ファイルに personal access token (classic) を追加して認証を行うには、プロジェクトの ~/.npmrc ファイルを編集して次の行を含めます。TOKEN は personal access token に置き換えます。 存在しない場合は、新しい ~/.npmrc ファイルを作成します。

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

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

npm CLI バージョン 9 以上を使用していて、コマンド ラインを使用してプライベート レジストリにログインまたはログアウトしている場合は、ブラウザー経由で既定のログイン フローを使用する代わりに、プロンプトから認証の詳細を読み取る --auth-type=legacy オプションを使用する必要があります。 詳細については、npm-loginを参照してください。

GitHub Packages が npm を使う場合の既定のパッケージ レジストリではなく、npm audit コマンドを使いたい場合は、GitHub Packages への認証を行うときに、パッケージをホストする名前空間 (パッケージがホストされているリポジトリを所有しており、パッケージのスコープ指定先となっている) で --scope フラグを使うことをお勧めします。

$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN

パッケージの公開

• パッケージ名とスコープには、小文字のみを使うことができます。
• npm バージョンの tarball のサイズは 256 MB 未満にする必要があります。

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

パッケージを最初に公開する際のデフォルトの可視性はプライベートです。 可視性の変更やアクセス許可の設定については、「パッケージのアクセス制御と可視性の設定」を参照してください。 公開されているパッケージをリポジトリにリンクする方法の詳細については、「リポジトリのパッケージへの接続」を参照してください。

repository フィールド の package.json ファイル に含めることで、パッケージが発行されるとすぐにパッケージを リポジトリに 接続できます。 このメソッドは、複数のパッケージを同じリポジトリに接続するためにも使えます。 詳細については、「同じリポジトリへの複数パッケージの公開」を参照してください。

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

パッケージを公開した後は、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 を指定する行と、パッケージがホストされている名前空間を含めます。 NAMESPACE を、プロジェクトを含むリポジトリを所有しており、パッケージのスコープ指定先となる。

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

3. GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。 詳しくは、「ファイルをリポジトリに追加する」を参照してください。

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

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

6. パッケージを公開してください。

   npm publish
   

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

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

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

   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   },
   

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

3. パッケージを公開してください。

   npm publish
   

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

複数のパッケージを同じリポジトリに公開して リンクする 場合は、GitHub リポジトリの URL を、各パッケージの repository フィールド の package.json ファイル に含めます。 詳細については、npm ドキュメントの「Creating a package.json file」(package.json ファイルの作成) と「Creating Node.js modules」(Node.js モジュールの作成) を参照してください。

リポジトリの URL が正しいことを確認するには、REPOSITORY は発行したいパッケージを含むリポジトリの名前に、OWNER はリポジトリを所有している GitHub の個人アカウントまたは Organization の名前に置き換えます。

GitHub Packages によって、パッケージ名ではなく URL。

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

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

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

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

プロジェクトに .npmrc ファイルを追加して、パッケージをインストールするためのすべての要求が GitHub Packagesを経由するようにする必要もあります。 すべてのパッケージリクエストを GitHub Packages 経由にする場合、npmjs.org からスコープ付きとスコープ付きでないパッケージの両方を利用できます。詳細については、npm ドキュメントの「npm-scope」を参照してください。

1. GitHub Packagesに認証を受けてください。 詳細については、「GitHub Packages への認証」を参照してください。

2. package.json ファイルと同じディレクトリで、.npmrc ファイルを作成または編集して、GitHub Packages URL を指定する行と、パッケージがホストされている名前空間を含めます。 NAMESPACE を、プロジェクトを含むリポジトリを所有しており、パッケージのスコープ指定先となる。

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

3. GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。 詳しくは、「ファイルをリポジトリに追加する」を参照してください。

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

   {
     "name": "@my-org/server",
     "version": "1.0.0",
     "description": "Server app that uses the ORGANIZATION_NAME/PACKAGE_NAME package",
     "main": "index.js",
     "author": "",
     "license": "MIT",
     "dependencies": {
       "ORGANIZATION_NAME/PACKAGE_NAME": "1.0.0"
     }
   }
   

5. パッケージをインストールします。

   npm install
   

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

デフォルトでは、1つのOrganizationからのみGitHub Packagesパッケージを利用できます。 パッケージ要求を複数の Organization とユーザーにルーティングする場合は、 .npmrc ファイルに行を追加し、 NAMESPACE は、プロジェクトを含むリポジトリを所有しており、パッケージのスコープ指定先となっている。

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