Githubでパッケージ管理 Github Packagesとは？

はじめに

業務でGitHubを使っていると、社内ライブラリやプライベートなnpmパッケージを安全に共有したい場面が出てきます。
この記事では、GitHubが提供するパッケージレジストリサービス GitHub Packages の概要と、npmパッケージを例にした具体的な使い方を紹介します。

GitHub Packagesとは

GitHub Packagesは、GitHubが提供するパッケージホスティングサービスです。
ソースコードとパッケージを一元管理でき、GitHubのアクセス権限管理やGitHub Actionsと密接に連携しています。

サポートされているレジストリ

パッケージマネージャー	対応言語/用途
npm	JavaScript / Node.js
RubyGems	Ruby
Apache Maven / Gradle	Java
NuGet	.NET
Container registry	Docker / OCI イメージ

npmとの違い

比較項目	npm registry	GitHub Packages
パッケージの公開先	npmの公開レジストリ	GitHubリポジトリに紐づく
アクセス管理	npm組織単位	GitHubのOrg/リポジトリ権限を継承
認証	npm token	GitHub Personal Access Token
GitHub Actionsとの連携	別途設定が必要	GITHUB_TOKENで自動認証可能

ユースケース

• 社内限定の共通ライブラリをプライベートで配布したい
• npmに公開するほどではないが、複数リポジトリで使い回したいコードがある
• GitHub Actionsのワークフロー内でパッケージの公開・利用を自動化したい

導入手順（npm の場合）

1. Personal Access Tokenの発行

GitHub Packagesへの認証には Personal Access Token (classic) が必要です。

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 「Generate new token (classic)」をクリック
3. 以下のスコープにチェックを入れてトークンを発行

スコープ	用途
read:packages	パッケージのダウンロード
write:packages	パッケージのアップロード
delete:packages	パッケージの削除

Fine-grained tokenはサポートされていません。
必ずclassicトークンを使用してください。

2. 認証設定

グローバルの ~/.npmrc にトークンを追加します。

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

3. パッケージの公開

package.json の設定

パッケージ名はGitHubの @スコープ付き にする必要があります。

{
  "name": "@YOUR_ORG_OR_USERNAME/PACKAGE_NAME",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/YOUR_ORG_OR_USERNAME/REPO_NAME.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

公開実行

npm publish

初回公開時はデフォルトで プライベート になります。公開範囲はGitHub上のパッケージ設定から変更できます。

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

インストール側のプロジェクトでも認証設定が必要です。

プロジェクトの .npmrc に追加

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

package.json に依存関係を追加

{
  "dependencies": {
    "@YOUR_ORG_OR_USERNAME/PACKAGE_NAME": "1.0.0"
  }
}

インストール実行

npm install

アクセス権限の管理

GitHub Packagesでは、パッケージに対して3段階の権限を設定できます。

権限	できること
Read	ダウンロード・メタデータの参照
Write	アップロード・ダウンロード・メタデータの読み書き
Admin	削除・管理・権限付与を含む全操作

デフォルトでは、リポジトリのアクセス権限を継承します。
Container registry / npm / NuGet / RubyGems では、リポジトリとは独立して権限を設定することも可能です。

GitHub Actionsとの連携

GitHub Actionsのワークフロー内では、GITHUB_TOKEN を使って追加設定なしに認証できます。

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://npm.pkg.github.com'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

トラブルシューティング

403 Forbidden でpublishできない
→ トークンに write:packages スコープが付与されているか確認してください。また、package.json の name が @スコープ/パッケージ名 形式になっているか確認してください。

npm install で 404 Not Found
→ .npmrc のスコープ設定が正しいか確認してください。プライベートパッケージの場合、インストール側にも認証済みトークンが必要です。

パッケージ名に大文字が含まれているとエラーになる
→ GitHub Packagesではパッケージ名とスコープに 小文字のみ 使用できます。

おわりに

GitHub Actionsと組み合わせることで、push時の自動publishなど、CI/CDに組み込んだワークフローも簡単に構築できます。

社内ライブラリをGitHub上で完結して管理・配布できるのは便利だなと思いました。

参考文献