MochiuWiki : SUSE, EC, PCB

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 を使用したパッケージのプル


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


参考リンク



「https://mochiu.net/index.php?title=GitHub_-_Packages&oldid=14580」から取得