npmレジストリの利用

GitHub Packages に認証を行う

メモ

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

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

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

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

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_TOKEN を使用する」を参照してください。アクションでレジストリを使うときのベストプラクティスについて詳しくは、「セキュリティで保護された使用に関するリファレンス」をご覧ください。

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

personal access tokenを使用した認証の実行

personal access token (classic) でパッケージを発行およびインストールするには、適切なスコープで GitHub Packages を使う必要があります。詳しくは、「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 コマンドを使用する場合は、--scopeに対して認証するときに、パッケージをホストする名前空間 (パッケージのスコープが指定された個人アカウントまたは組織) でGitHub Packages フラグを使用することをお勧めします。

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

> Username: USERNAME
> Password: TOKEN

パッケージの公開

メモ

パッケージ名とスコープには、小文字のみを使うことができます。

npm バージョンの tarball のサイズは 256 MB 未満にする必要があります。

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

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

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

メモ

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

プロジェクトのスコープマッピングは、プロジェクト内のローカル .npmrc ファイルか、publishConfig 内の package.json オプションを使って設定できます。 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組織に公開する場合、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
```

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

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 ファイルの repository フィールドにpackage.json リポジトリの URL を含めることができます。詳細については、npm ドキュメントの「Creating a package.json file」(package.json ファイルの作成) と「Creating Node.js modules」(Node.js モジュールの作成) を参照してください。

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

GitHub Packages は、パッケージ名ではなく、URL。

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

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

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

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

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

GitHub Packagesに認証を受けてください。詳しくは、「GitHub Packages への認証」をご覧ください。
package.json ファイルと同じディレクトリで、.npmrc ファイルを作成または編集して、GitHub Packages URL を指定する行と、パッケージがホストされている名前空間を含めます。 NAMESPACE を、プロジェクトを含むリポジトリを所有しており、パッケージのスコープ指定先となる。
```
@NAMESPACE:registry=https://npm.pkg.github.com
```
GitHub Packages でプロジェクトを見つけられるリポジトリに .npmrc ファイルを追加します。詳しくは、「ファイルをリポジトリに追加する」をご覧ください。
インストールするパッケージを使用するように、プロジェクトの package.json を構成します。 package.jsonのGitHub Packages ファイルにパッケージの依存関係を追加するには、@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 つの組織の GitHub Packages パッケージのみを使用できます。パッケージ要求を複数の組織とユーザーにルーティングする場合は、 .npmrc ファイルに行を追加し、 NAMESPACE を、パッケージのスコープが設定されている個人アカウントまたは組織の名前に置き換。

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

この記事で