GitHub - Packages

概要

GitHub Packagesは、GitHubが提供するソフトウェアパッケージホスティングサービスである。
ソースコードと同じリポジトリでパッケージを管理・公開・インストールできる。

GitHub Packagesが対応しているレジストリは以下の通りである。

GitHub Packagesの対応レジストリ一覧
レジストリ	説明
Container Registry(ghcr.io)	Dockerコンテナイメージおよび OCIイメージをホスティングする。
npm	JavaScriptパッケージをホスティングする。
Maven / Gradle	Javaパッケージをホスティングする。
NuGet	.NETパッケージをホスティングする。
RubyGems	Rubyパッケージをホスティングする。

GitHub Packagesを利用するメリットを以下に示す。

ソースコードとパッケージを同一リポジトリで管理できる。
GitHubのアクセス制御と統合されており、チームの権限管理が一元化できる。
GitHub Actionsとの連携により、CI/CDパイプラインにパッケージ公開を組み込める。
プライベートパッケージをリポジトリのアクセス権限に基づいて保護できる。

Container Registry (ghcr.io)

ghcr.ioはGitHubが提供するコンテナレジストリであり、DockerイメージおよびOCIイメージの管理に使用する。

認証

ghcr.ioへの認証には個人アクセストークン (Personal Access Token) を使用する。

下表に、必要なスコープを示す。

パーソナルアクセストークンのスコープ一覧
スコープ	説明
`read:packages`	パッケージのダウンロードとメタデータの読み取りに必要なスコープ
`write:packages`	パッケージのアップロードと公開に必要なスコープ
`delete:packages`	パッケージの削除に必要なスコープ

個人アクセストークンは、GitHubの[Settings] - [Developer settings] - [Personal access tokens]から作成できる。

Dockerログイン

ghcr.ioにログインする。

echo $CR_PAT | docker login ghcr.io -u <ユーザ名> --password-stdin

CR_PAT には個人アクセストークン、<ユーザ名> にはGitHubのユーザ名を指定する。
パスワードを標準入力から渡すことにより、コマンド履歴にトークンが残らないようにする。

イメージのプッシュとプル

ビルド済みのイメージにghcr.ioのタグを付けてプッシュする手順を以下に示す。

# イメージにタグを付ける
docker tag <イメージ名> ghcr.io/NAMESPACE/<イメージ名>:TAG

# イメージをプッシュする
docker push ghcr.io/NAMESPACE/<イメージ名>:TAG

# イメージをプルする
docker pull ghcr.io/NAMESPACE/<イメージ名>:TAG

NAMESPACE にはGitHubのユーザ名または Organization名を指定する。
TAG には latest やバージョン番号を指定する。

レイヤーの最大サイズは10[GB]、タイムアウトは10分である。

リポジトリの関連付け

コンテナイメージを特定のGitHubリポジトリに関連付けるには、Dockerfile内に以下のラベルを追加する。

LABEL org.opencontainers.image.source=https://github.com/OWNER/REPO

このラベルを追加すると、ghcr.io上のパッケージページから対象リポジトリへのリンクが表示される。
また、リポジトリの可視性設定がパッケージに継承される。

可視性設定

コンテナイメージの可視性は、GitHubのPackage settingsから設定できる。

パッケージの公開範囲一覧
公開範囲	説明
Public	誰でもプルできる状態
Private	アクセス権限を持つユーザのみプルできる状態

可視性をPublicからPrivateに変更することは、不可逆な操作であることに注意する。

npm レジストリ

GitHub Packagesのnpmレジストリを使用すると、スコープ付きnpmパッケージを公開・インストールできる。

認証と.npmrc設定

npmレジストリへの認証には、.npmrc ファイルを使用する。

プロジェクトルートに .npmrc ファイルを作成して、以下に示す内容を記述する。

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

NAMESPACE にはGitHubのユーザ名または Organization名を指定する。
TOKEN には read:packages スコープを持つ個人アクセストークンを指定する。

パッケージの公開

GitHub Packagesのnpmレジストリでは、スコープ付きパッケージ名が必須である。

package.json ファイル内の name フィールドを以下に示すように設定する。

 {
    "name": "@NAMESPACE/PACKAGE-NAME",
    "version": "1.0.0",
    "publishConfig": {
       "registry": "https://npm.pkg.github.com"
    }
 }

設定後、コマンドでパッケージを公開する。

npm publish

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

.npmrc ファイルにレジストリ設定を追加した後、以下のコマンドでパッケージをインストールする。

npm install @NAMESPACE/PACKAGE-NAME

Maven レジストリ

GitHub PackagesのMavenレジストリを使用すると、JavaのMavenパッケージを公開・インストールできる。

認証設定

Mavenの認証情報は ~/.m2/settings.xml ファイルに設定する。

 <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
    <servers>
       <server>
          <id>github</id>
          <username>USERNAME</username>
          <password>TOKEN</password>
       </server>
    </servers>
 </settings>

USERNAME には GitHubのユーザ名、TOKEN には read:packages または write:packages スコープを持つ個人アクセストークンを指定する。

パッケージの公開

pom.xml ファイルの distributionManagement セクションにリポジトリURLを設定する。

 <distributionManagement>
    <repository>
       <id>github</id>
       <name>GitHub OWNER Apache Maven Packages</name>
       <url>https://maven.pkg.github.com/OWNER/REPO</url>
    </repository>
 </distributionManagement>

設定後、パッケージをデプロイするため、以下に示すコマンドを実行する。

mvn deploy

アーティファクトIDは、小文字のみが使用できることに注意する。

Gradleでの使用

Gradleを使用する場合は、build.gradle ファイルにリポジトリと認証情報を設定する。

 repositories {
    maven {
       url = uri("https://maven.pkg.github.com/OWNER/REPO")
       credentials {
          username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
          password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
       }
    }
 }

NuGetレジストリ

GitHub PackagesのNuGetレジストリを使用すると、.NETのNuGetパッケージを公開・インストールできる。

パッケージの公開

NuGetパッケージを公開するため、以下に示すコマンドを実行する。

dotnet nuget push PACKAGE_NAME.nupkg \
   --api-key <TOKEN> \
   --source "https://nuget.pkg.github.com/OWNER/index.json"

TOKEN には write:packages スコープを持つ個人アクセストークンを指定する。

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

nuget.config ファイルにGitHub Packagesのソースを追加する。

 <?xml version="1.0" encoding="utf-8"?>
 <configuration>
    <packageSources>
       <add key="github" value="https://nuget.pkg.github.com/OWNER/index.json" />
    </packageSources>
    <packageSourceCredentials>
       <github>
          <add key="Username" value="USERNAME" />
          <add key="ClearTextPassword" value="TOKEN" />
       </github>
    </packageSourceCredentials>
 </configuration>

設定後、dotnetコマンドでパッケージをインストールできる。

dotnet add package <パッケージ名>

RubyGemsレジストリ

GitHub PackagesのRubyGemsレジストリを使用すると、RubyのGemパッケージを公開・インストールできる。

パッケージの公開

まず ~/.gem/credentials ファイルに認証情報を設定する。

 :github: Bearer TOKEN

次に、Gemをビルドして公開するため、以下に示すコマンドを実行する。

# Gemのビルド
gem build PACKAGE_NAME.gemspec

# GitHub Packagesへのプッシュ
gem push --key github \
   --host https://rubygems.pkg.github.com/NAMESPACE \
   PACKAGE_NAME-VERSION.gem

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

Bundlerを使用してインストールする場合は、Gemfile ファイルに以下の設定を追加する。

 source "https://rubygems.pkg.github.com/NAMESPACE" do
    gem "PACKAGE_NAME"
 end

設定後、以下に示すコマンドを実行して、インストールする。

bundle install

GitHub Actionsとの連携

GitHub ActionsからGitHub Packagesへのアクセスには GITHUB_TOKEN を使用できる。

GITHUB_TOKEN を使用することにより、個人アクセストークンを別途作成せずにパッケージを公開できる。

Dockerイメージの自動公開

Dockerイメージを自動的にghcr.ioに公開するワークフローの例を以下に示す。

 name: Publish Docker Image
 
 on:
    push:
       branches:
          - main
 
 jobs:
    publish:
       runs-on: ubuntu-latest
       permissions:
          contents: read
          packages: write
 
       steps:
          - name: Checkout repository
            uses: actions/checkout@v4
 
          - name: Log in to the Container registry
            uses: docker/login-action@v3
            with:
               registry: ghcr.io
               username: ${{ github.actor }}
               password: ${{ secrets.GITHUB_TOKEN }}
 
          - name: Build and push Docker image
            uses: docker/build-push-action@v5
            with:
               context: .
               push: true
               tags: ghcr.io/${{ github.repository }}:latest

下表に、主なアクションを示す。

Docker関連アクション一覧
アクション	説明
`docker/login-action`	コンテナレジストリへのログインを行うアクション
`docker/build-push-action`	Dockerイメージのビルドとプッシュを行うアクション

npmパッケージの自動公開

npmパッケージを自動的に公開するワークフローの例を以下に示す。

 name: Publish npm Package
 
 on:
    release:
       types: [created]
 
 jobs:
    publish:
       runs-on: ubuntu-latest
       permissions:
          contents: read
          packages: write
 
       steps:
          - name: Checkout repository
            uses: actions/checkout@v4
 
          - name: Setup Node.js
            uses: actions/setup-node@v4
            with:
               node-version: '20'
               registry-url: 'https://npm.pkg.github.com'
               scope: '@NAMESPACE'
 
          - name: Install dependencies
            run: npm ci
 
          - name: Publish package
            run: npm publish
            env:
               NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

環境変数 NODE_AUTH_TOKEN に GITHUB_TOKEN を設定することにより、認証を行う。

パッケージの管理

GitHub Packagesのパッケージは、[リポジトリ]ページまたは [Organization]ページから管理できる。

バージョン管理

公開したパッケージは複数バージョンを保持できる。
各バージョンは個別に管理・削除が可能である。

バージョン一覧は、[リポジトリ]ページの[Packages]セクションまたは [Organization]ページの[Packages]ページから確認できる。

アクセス権限

パッケージのアクセス権限は以下に示す3段階で設定できる。

パッケージのアクセス権限
権限	説明
Read	パッケージのダウンロードとメタデータの閲覧が可能
Write	パッケージの公開と新バージョンのアップロードが可能
Admin	権限設定の変更、パッケージの削除、可視性の変更が可能

デフォルトでは、リポジトリのアクセス権限がパッケージに継承される。

リポジトリ権限の継承は、パッケージの設定から無効化することもできる。

パッケージの削除と復元

パッケージのバージョンは、GitHubのWeb UI または GraphQL APIを使用して削除できる。

削除したパッケージは30日以内であれば復元できる。
復元には以下の条件が必要である。

同じ名前空間とバージョン番号が現在使用されていないこと。
削除から30日以内であること。

可視性の変更

パッケージの可視性変更に関して、以下に示す重要な制限がある。

PublicからPrivateへの変更は不可逆である。
1度Privateに変更すると、同じパッケージ名でPublicに戻すことはできない。
PrivateからPublicへの変更は可能である。
ただし、Publicにした場合は全員がアクセスできる状態になることに注意する。

課金

GitHub Packagesの利用には、ストレージ容量とデータ転送量に応じた課金が発生する場合がある。

無料枠

下表に、各プランの無料枠を示す。

GitHub Packages の無料枠
プラン	ストレージ	データ転送 (月間)
Free	500[MB]	1[GB]
Pro	2[GB]	10[GB]
Team	2[GB]	10[GB]
Enterprise	50[GB]	100[GB]

無料枠を超えた場合は追加費用が発生する。

GITHUB_TOKENでのデータ転送

GitHub Actionsワークフロー内で GITHUB_TOKEN を使用して GitHub Packages にアクセスする場合、データ転送量は無料枠の割当を消費しない。

これは、以下のケースに該当する。

ワークフロー内での GITHUB_TOKEN を使用したパッケージのプッシュ
ワークフロー内での GITHUB_TOKEN を使用したパッケージのプル

個人アクセストークンを使用した場合は、通常通り割当が消費されることに注意する。

参考リンク