Skip to main content

npmレジストリの利用

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

この機能を使用できるユーザーについて

GitHub Packagesは、GitHub Free、GitHub Pro、組織用GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0以降で利用できます。
GitHub Packagesは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 また、従来のリポジトリごとのプランを利用しているアカウントは、リポジトリごとに課金されるため、詳細なアクセス許可をサポートしているレジストリにはアクセスできません。 詳細なアクセス許可をサポートするレジストリの一覧については、「GitHub Packagesの権限について」を参照してください。 詳しくは、「GitHub のプラン」をご覧ください。

GitHub Packages への認証を行う

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

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

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でのパッケージの公開とインストール」をご覧ください。

注: GitHub Actions ワークフローで REST API を使用してパッケージを削除および復元する機能は、現在パブリック ベータ版であり、変更される可能性があります。

トークンにパッケージに対する 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 ファイル に含めることで、パッケージが発行されるとすぐにパッケージを リポジトリに 接続できます。 このメソッドは、複数のパッケージを同じリポジトリに接続するためにも使えます。 詳しくは、「同じリポジトリへの複数パッケージの公開」をご覧ください。

注: リポジトリにリンクされているパッケージを公開した場合、パッケージは自動的にリンクされたリポジトリのアクセス許可を継承し、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 に誤って公開することを防止できます。

  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.jsonrepository フィールドを確認します。 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.jsonrepository フィールドを確認します。 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 ドキュメントの「package.json ファイルの作成」と「Node.js モジュールの作成」を参照してください。

リポジトリの 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 を指定する行と、パッケージがホストされている名前空間を含めます。 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