npmレジストリの利用

GitHub Packages への認証を行う

メモ

GitHub Packages では、personal access token (classic)を使用した認証のみがサポートされています。詳しくは、「個人用アクセストークンを管理する」をご覧ください。

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

GitHub Packages、あるいは GitHub API で認証を受けるのに、personal access token (classic) を利用できます。 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でのパッケージの公開とインストール」をご覧ください。

メモ

REST API を使ってパッケージを削除および復元する 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 にログインします。

personal access token (classic) を ~/.npmrc ファイルに追加して認証するには、プロジェクトの ~/.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 ファイルに含めることで、パッケージが発行されるとすぐにパッケージをリポジトリに接続できます。このメソッドは、複数のパッケージを同じリポジトリに接続するためにも使えます。詳細については、「同じリポジトリへの複数パッケージの公開」を参照してください。

メモ

リポジトリにリンクされているパッケージを公開した場合、organization でアクセス許可の自動継承が無効にされていない限り、パッケージはリンクされたリポジトリのアクセス許可を自動的に継承し、リンクされたリポジトリ内の GitHub Actions ワークフローは自動的にパッケージにアクセスできるようになります。詳しくは、「パッケージのアクセス制御と可視性の設定」をご覧ください。

プロジェクトのスコープマッピングは、プロジェクト内のローカル .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 にパッケージを公開することを防ぐことができます。

GitHub Packagesに認証を受けてください。詳しくは、「GitHub Packages への認証」をご覧ください。
package.json ファイルと同じディレクトリで、.npmrc ファイルを作成または編集して、GitHub Packages URL を指定する行と、パッケージがホストされている名前空間を含めます。 NAMESPACE を、プロジェクトを含むリポジトリを所有しており、パッケージのスコープ指定先となる。
```
@NAMESPACE:registry=https://npm.pkg.github.com
```
GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。詳しくは、「ファイルをリポジトリに追加する」をご覧ください。
プロジェクトの package.json にあるパッケージの名前を確認します。 name フィールドには、スコープとパッケージの名前が含まれている必要があります。たとえば、パッケージの名前が「test」で、"My-org" GitHub Organization に公開する場合、package.json内のnameフィールドを@my-org/testにする必要があります。
プロジェクトの package.json の repository フィールドを確認します。 repository フィールドは、GitHub リポジトリの URL と一致している必要があります。たとえば、リポジトリの URL が github.com/my-org/test である場合、repository フィールドは https://github.com/my-org/test.git でなければなりません。
パッケージを公開してください。
```
npm publish
```

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

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

パッケージの package.json ファイルを編集して、publishConfig のエントリを含めるようにします。
```
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
},
```
プロジェクトの package.json の repository フィールドを確認します。 repository フィールドは、GitHub リポジトリの URL と一致している必要があります。たとえば、リポジトリの URL が github.com/my-org/test である場合、repository フィールドは https://github.com/my-org/test.git でなければなりません。
パッケージを公開してください。
```
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 からのパッケージのインストール」を参照してください。

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

GitHub Packagesに認証を受けてください。詳しくは、「GitHub Packages への認証」をご覧ください。
package.json ファイルと同じディレクトリで、.npmrc ファイルを作成または編集して、GitHub Packages URL を指定する行と、パッケージがホストされている名前空間を含めます。 NAMESPACE を、プロジェクトを含むリポジトリを所有しており、パッケージのスコープ指定先となる。
```
@NAMESPACE:registry=https://npm.pkg.github.com
```
GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。詳しくは、「ファイルをリポジトリに追加する」をご覧ください。
インストールするパッケージを使用するように、プロジェクトの 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"
  }
}
```
パッケージをインストールします。
```
npm install
```

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

デフォルトでは、1つのOrganizationからのみGitHub Packagesパッケージを利用できます。パッケージ要求を複数の organization とユーザーにルーティングする場合は、.npmrc ファイルに行を追加します。その際に、NAMESPACE はパッケージのスコープが設定されている個人用アカウントまたは組織の名前に置き換えます。

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