GitHub Packagesがサポートするパッケージとは

Posted at 2025-12-23

GitHub Packagesがサポートするパッケージとは

GitHub Packagesは、様々な言語やフレームワークのパッケージを一元管理できるサービスです。本記事では、公式ドキュメントをもとに、各レジストリの特徴と実践的な使い方を解説します。

1. GitHub Packagesが対応するレジストリ

GitHub Packagesは、以下の6つのレジストリをサポートしています。

レジストリ	用途	主な対象言語
Container registry	Docker/OCIイメージ	言語非依存
npm registry	Node.jsパッケージ	JavaScript/TypeScript
RubyGems registry	Gemパッケージ	Ruby
Apache Maven registry	Mavenパッケージ	Java
Gradle registry	Gradleパッケージ	Java/Kotlin
NuGet registry	NuGetパッケージ	C#/.NET

なお、Docker registryは既にContainer registryに統合されており、docker.pkg.github.comからghcr.ioへの移行が進められています。

2. 全レジストリ共通の基本概念

2.1 認証方式

すべてのレジストリで共通して、Personal Access Token (classic)を使った認証が必要です。トークンには用途に応じたスコープを設定します。

必要なスコープ

read:packages - パッケージのダウンロードとメタデータ読み取り
write:packages - パッケージのアップロードと読み書き
delete:packages - パッケージの削除

GitHub Actionsでの認証

ワークフロー内ではGITHUB_TOKENの使用が推奨されます。これにより、以下のメリットがあります。

トークンの手動管理が不要
ワークフローリポジトリに紐付いたパッケージの公開が可能
適切な権限が自動的に付与される

- name: パッケージを公開
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    # 各レジストリのコマンド

2.2 パッケージの可視性とアクセス制御

パッケージを初めて公開する際、デフォルトの可視性はプライベートです。以下の2つの方法でアクセス制御を設定できます。

リポジトリからの継承 - リポジトリのアクセス権限をパッケージが自動的に継承
独立した権限設定 - リポジトリとは別に詳細な権限を個別設定

リポジトリに紐付けられたパッケージは、そのリポジトリのGitHub Actionsワークフローから自動的にアクセス可能になります（組織の設定で無効化されていない限り）。

Container registry - コンテナイメージの管理

Container registryはghcr.ioドメインで提供され、Docker Image Manifest V2とOpen Container Initiative (OCI)仕様をサポートしています。

技術的制約

レイヤーサイズ上限: 10GB/レイヤー
アップロードタイムアウト: 10分
対応フォーマット: Docker Image Manifest V2 Schema 2、OCI仕様

3.2 認証とログイン

Personal Access Tokenを環境変数に設定し、Dockerクライアントでログインします。

# トークンを環境変数に設定
export CR_PAT=YOUR_TOKEN

# Container registryにログイン
echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

3.3 イメージのビルドとタグ付け

# イメージをビルド
docker build -t hello_docker .

# イメージIDを確認
docker images

# タグを付与（NAMESPACEは個人アカウントまたは組織名）
docker tag 38f737a91f39 ghcr.io/NAMESPACE/IMAGE_NAME:latest

3.4 メタデータの追加

Dockerfileに事前定義されたアノテーションキーを使用することで、パッケージページに表示されるメタデータを追加できます。

LABEL org.opencontainers.image.source=https://github.com/yamada/my-repo
LABEL org.opencontainers.image.description="私のコンテナイメージ"
LABEL org.opencontainers.image.licenses=MIT

サポートされるアノテーションキー

キー	説明	制限
`org.opencontainers.image.source`	関連リポジトリのURL	-
`org.opencontainers.image.description`	テキスト説明	512文字
`org.opencontainers.image.licenses`	SPDXライセンス識別子	256文字

特にorg.opencontainers.image.sourceを設定すると、パッケージが自動的にリポジトリに接続され、GITHUB_TOKENが適切な権限を持つようになります。

3.5 イメージの公開

# 最新版を公開
docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest

# 特定バージョンを公開
docker push ghcr.io/NAMESPACE/IMAGE_NAME:2.5

3.6 イメージの取得

ダイジェスト値による取得（推奨）

同一イメージを確実に取得するため、SHA値を使用します。

# ダイジェスト値を確認
docker inspect ghcr.io/NAMESPACE/IMAGE_NAME

# ダイジェスト値で取得
docker pull ghcr.io/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

タグによる取得

# 最新版を取得
docker pull ghcr.io/NAMESPACE/IMAGE_NAME:latest

# 特定バージョンを取得
docker pull ghcr.io/NAMESPACE/IMAGE_NAME:1.14.1

3.7 マルチアーキテクチャイメージ

マルチアーキテクチャイメージでは、マニフェストのannotationsフィールドに説明を追加します。

"annotations": {
  "org.opencontainers.image.description": "マルチアーキテクチャ対応イメージ"
}

GitHub Actionsでの例：

- name: イメージをビルドして公開
  uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=マルチアーキテクチャ対応イメージ

npm registry - Node.jsパッケージの管理

npm registryはhttps://npm.pkg.github.comで提供され、スコープ付きパッケージのみをサポートします。

技術的制約

命名規則: パッケージ名とスコープは小文字のみ
tarballサイズ上限: 256MB/バージョン
必須形式: @NAMESPACE/PACKAGE-NAME

4.2 認証設定

~/.npmrcファイルによる認証

# ~/.npmrcファイルを編集
//npm.pkg.github.com/:_authToken=TOKEN

コマンドラインでのログイン

npm CLI 9以降では--auth-type=legacyオプションが必要です。

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

# プロンプトで入力
# Username: USERNAME
# Password: TOKEN
# Email: PUBLIC-EMAIL-ADDRESS

4.3 パッケージの公開

方法1: .npmrcファイルを使用

プロジェクトディレクトリに.npmrcファイルを作成します。

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

package.jsonの設定例：

{
  "name": "@my-org/test",
  "version": "1.0.0",
  "repository": "https://github.com/my-org/test.git"
}

公開コマンド：

npm publish

方法2: publishConfigを使用

package.jsonに直接設定を記述します。

{
  "name": "@my-org/test",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  },
  "repository": "https://github.com/my-org/test.git"
}

複数パッケージの同一リポジトリへの公開

repositoryフィールドに同じURLを設定することで、複数のパッケージを同じリポジトリに紐付けられます。

{
  "name": "@my-org/package-a",
  "repository": "https://github.com/my-org/my-repo"
}

{
  "name": "@my-org/package-b",
  "repository": "https://github.com/my-org/my-repo"
}

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

プロジェクトの.npmrcファイルを設定します。

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

package.jsonに依存関係を追加：

{
  "dependencies": {
    "@my-org/package-name": "1.0.0"
  }
}

インストール実行：

npm install

複数の組織からのインストール

@org1:registry=https://npm.pkg.github.com
@org2:registry=https://npm.pkg.github.com

RubyGems registry - Ruby gemの管理

RubyGems registryはhttps://rubygems.pkg.github.comで提供されます。

前提条件

RubyGems 2.4.1以上
Bundler 1.6.4以上

5.2 認証設定

RubyGemsでの認証（gem公開用）

~/.gem/credentialsファイルを作成または編集します。

---
:github: Bearer TOKEN

Bundlerでの認証（gemインストール用）

bundle config https://rubygems.pkg.github.com/NAMESPACE USERNAME:TOKEN

または、gem sourcesに追加：

gem sources --add https://USERNAME:TOKEN@rubygems.pkg.github.com/NAMESPACE/

5.3 gemの公開

gemspecからgemをビルドし、公開します。

# gemをビルド
gem build GEM_NAME.gemspec

# GitHub Packagesに公開
gem push --key github \
  --host https://rubygems.pkg.github.com/NAMESPACE \
  GEM_NAME-0.0.1.gem

注意: metadata.gzファイルの非圧縮サイズは2MB未満である必要があります。

5.4 リポジトリへの自動接続

gem.metadataにgithub_repoフィールドを設定すると、公開時に自動的にリポジトリに紐付けられます。

gem.metadata = { "github_repo" => "ssh://github.com/OWNER/REPOSITORY" }

5.5 gemのインストール

Bundlerを使用する場合

Gemfileにソースを追加します。

source "https://rubygems.org"

gem "rails"

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

Bundler 1.7.0以前の場合：

source "https://rubygems.pkg.github.com/NAMESPACE"
source "https://rubygems.org"

gem "rails"
gem "GEM_NAME"

直接インストール

gem install GEM_NAME --version "0.1.1"

Apache Maven registry - Javaパッケージの管理（Maven）

Maven registryはhttps://maven.pkg.github.comで提供されます。

認証設定

~/.m2/settings.xmlファイルを作成または編集します。

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo.maven.apache.org/maven2</url>
        </repository>
        <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
  </servers>
</settings>

重要: リポジトリオーナー名は小文字で指定する必要があります。GitHubのユーザー名や組織名に大文字が含まれていても、設定では小文字に変換してください。

6.2 パッケージの公開

pom.xmlファイルのdistributionManagement要素を編集します。

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

注意事項: artifactIdは小文字、数字、ハイフンのみを含む必要があります。大文字を使用すると422 Unprocessable Entityエラーが発生します。

公開コマンド：

mvn deploy

6.3 複数パッケージの公開

distributionManagement要素に同じリポジトリURLを設定することで、複数のパッケージを同じリポジトリに公開できます。

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

pom.xmlのdependencies要素に依存関係を追加します。

<dependencies>
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>test</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </dependency>
</dependencies>

インストール実行：

mvn install

特定のオーナーのすべてのリポジトリからパッケージをインストールする場合は、https://maven.pkg.github.com/OWNER/*のようなURLを使用できます。

Gradle registry - Javaパッケージの管理（Gradle）

Gradle registryはhttps://maven.pkg.github.comで提供され、MavenフォーマットのリポジトリとしてGradleから利用できます。

認証設定

build.gradle（Gradle Groovy）またはbuild.gradle.kts（Kotlin DSL）ファイルを編集します。

Gradle Groovy - 単一パッケージ

plugins {
    id("maven-publish")
}

publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
                password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
            }
        }
    }
    publications {
        gpr(MavenPublication) {
            from(components.java)
        }
    }
}

Kotlin DSL - 単一パッケージ

plugins {
    `maven-publish`
}

publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
            credentials {
                username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
                password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
            }
        }
    }
    publications {
        register<MavenPublication>("gpr") {
            from(components["java"])
        }
    }
}

複数パッケージの設定（Gradle Groovy）

plugins {
    id("maven-publish") apply false
}

subprojects {
    apply plugin: "maven-publish"
    publishing {
        repositories {
            maven {
                name = "GitHubPackages"
                url = uri("https://maven.pkg.github.com/OWNER/REPOSITORY")
                credentials {
                    username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
                    password = project.findProperty("gpr.key") ?: System.getenv("TOKEN")
                }
            }
        }
        publications {
            gpr(MavenPublication) {
                from(components.java)
            }
        }
    }
}

7.2 パッケージの公開

gradle publish

デフォルトでは、パッケージ名と同じ名前の既存リポジトリに公開されます。例えば、com.example.testというパッケージはOWNER/testリポジトリに公開されます。

7.3 パッケージの使用

依存関係の追加（Gradle Groovy）

dependencies {
    implementation 'com.example:package'
}

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

依存関係の追加（Kotlin DSL）

dependencies {
    implementation("com.example:package")
}

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

NuGet registry - .NETパッケージの管理

NuGet registryはhttps://nuget.pkg.github.comで提供されます。

技術的制約

nupkgアーカイブサイズ上限: 2.147GB/バージョン

8.2 認証設定

プロジェクトディレクトリにnuget.configファイルを作成します。

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

8.3 GitHub Actionsでの認証

dotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "https://nuget.pkg.github.com/NAMESPACE/index.json"

8.4 パッケージの公開

方法1: Personal Access TokenをAPIキーとして使用

# ソースを追加
dotnet nuget add source --username OWNER --password YOUR_GITHUB_PAT --store-password-in-clear-text --name github "https://nuget.pkg.github.com/OWNER/index.json"

# プロジェクトを作成
dotnet new console --name PROJECT_NAME

# パッケージ化
dotnet pack --configuration Release

# 公開
dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --api-key YOUR_GITHUB_PAT --source "github"

方法2: nuget.configファイルを使用

.csprojファイルにプロジェクト情報を追加します。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>PROJECT_NAME</PackageId>
    <Version>1.0.0</Version>
    <Authors>山田太郎</Authors>
    <Company>株式会社サンプル</Company>
    <PackageDescription>パッケージの説明</PackageDescription>
    <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

パッケージ化と公開：

dotnet pack --configuration Release
dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source "github"

8.5 複数パッケージの公開

複数のパッケージを同じリポジトリに接続するには、各.csprojファイルのRepositoryUrlフィールドに同じGitHubリポジトリURLを設定します。

<!-- プロジェクト1 -->
<PropertyGroup>
  <PackageId>MY_APP</PackageId>
  <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
</PropertyGroup>

<!-- プロジェクト2 -->
<PropertyGroup>
  <PackageId>MY_OTHER_APP</PackageId>
  <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
</PropertyGroup>

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

.csprojファイルにItemGroupとPackageReferenceを追加します。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>My-app</PackageId>
    <Version>1.0.0</Version>
    <Authors>山田太郎</Authors>
    <Company>GitHub</Company>
    <PackageDescription>アプリの説明</PackageDescription>
    <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PACKAGE_NAME" Version="X.X.X" />
  </ItemGroup>

</Project>

復元コマンドでインストール：

dotnet restore

8.7 トラブルシューティング

GitHub Actionsワークフロー内でGITHUB_TOKENを使用する場合、そのトークンは実行中のリポジトリ以外のプライベートリポジトリベースのパッケージにアクセスできません。他のリポジトリに関連するパッケージにアクセスするには、read:packagesスコープを持つPersonal Access Token (classic)を生成し、シークレットとして渡す必要があります。

9. パッケージ管理のベストプラクティス

9.1 ワークフロー全体の流れ

9.2 セキュリティのポイント

Personal Access Tokenの管理
- トークンは環境変数またはシークレットマネージャーで管理
- リポジトリに直接コミットしない
- 必要最小限のスコープのみを付与
GitHub Actionsでの自動化
- GITHUB_TOKENを優先的に使用
- Personal Access Tokenは必要な場合のみ使用
- シークレットとして安全に保管
アクセス制御
- プライベートパッケージには適切な権限設定
- リポジトリベースの権限継承を活用
- 組織レベルでのポリシー設定

9.3 バージョン管理の戦略

各レジストリで一貫したバージョニング戦略を採用することで、依存関係の管理が容易になります。

セマンティックバージョニングの例

1.0.0 - メジャーバージョン（破壊的変更）
1.1.0 - マイナーバージョン（後方互換性のある機能追加）
1.1.1 - パッチバージョン（バグ修正）

SNAPSHOTバージョン（Maven/Gradle）

開発中のバージョンには-SNAPSHOTサフィックスを使用します。

<version>1.0.0-SNAPSHOT</version>

9.4 CI/CDパイプラインへの統合

GitHub Actionsを使用した自動公開の例：

name: パッケージ公開

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    
    steps:
    - uses: actions/checkout@v4
    
    - name: 環境セットアップ
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        registry-url: 'https://npm.pkg.github.com'
    
    - name: 依存関係インストール
      run: npm ci
    
    - name: パッケージ公開
      run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

10. まとめ

GitHub Packagesは、複数の言語やフレームワークに対応した統合パッケージ管理サービスです。各レジストリには以下の共通点があります。

認証とアクセス制御

Personal Access Token (classic)による統一的な認証
GitHub ActionsでのGITHUB_TOKENサポート
リポジトリベースの権限継承

パッケージの公開と管理

デフォルトでプライベート公開
リポジトリへの自動接続機能
バージョン管理とメタデータのサポート

技術的制約

レジストリごとに異なるサイズ制限
命名規則の遵守が必要
言語固有のツールとの統合

GitHub Packagesを活用することで、プライベートパッケージの管理、チーム内での共有、CI/CDパイプラインへの統合が効率的に実現できます。各レジストリの特性を理解し、プロジェクトに適した設定を行うことで、開発プロセス全体の生産性向上につながります。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up