コンテナレジストリの利用

Docker イメージと OCI イメージは、Container registry に保存して管理できます。

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

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

この記事の内容

Container registry について

Container registry は、Organization または個人アカウント内にコンテナーイメージを格納し、イメージをリポジトリに関連付けることができます。権限をリポジトリから継承するか、リポジトリとは別に細かい権限を設定するかを選ぶことができます。パブリックコンテナーイメージに匿名でアクセスすることもできます。

Container registryサポートについて

現在のところ、Container registry では以下のコンテナフォーマットをサポートしています。

Dockerイメージをインストールあるいは公開する際には、Container registryはWindowsイメージのような外部レイヤーもサポートします。

Container registryでの認証

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 (classic)

で認証を行う

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

実行したいタスクに対して適切なスコープを持つ新しい personal access token (classic) を作成してください。 OrganizationがSSOを必須としている場合は、新しいトークンでSSOを有効化しなければなりません。

注: 既定では、ユーザーインターフェイスで personal access token (classic) の write:packages スコープを選択すると、repo スコープも選択されます。 repo スコープは不要に広いアクセス権を提供するので、特に GitHub Actions ワークフローでの利用は避けることをお勧めします。詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。回避策として、URL https://github.com/settings/tokens/new?scopes=write:packages のユーザーインターフェイスで自分の personal access token (classic) だけの write:packages スコープを選択できます。
- read:packages スコープを選択すると、コンテナーイメージがダウンロードされ、そのメタデータが読み取られます。
- write:packages スコープを選択すると、コンテナーイメージがダウンロードされ、アップロードされ、そのメタデータが読み書きされます。
- delete:packages スコープを選択すると、コンテナーイメージが削除されます。
詳しくは、「個人用アクセストークンを管理する」を参照してください。
personal access token (classic) を保存します。トークンは環境変数として保存することをおすすめします。
```
export CR_PAT=YOUR_TOKEN
```
コンテナーの種類に CLI を使用し、ghcr.io で Container registry サービスにサインインします。
```
$ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
> Login Succeeded
```

コンテナイメージをプッシュする

この例では、最新バージョンの IMAGE_NAME をプッシュします。

docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest

NAMESPACE を、イメージのスコープ指定先にしたい個人アカウントまたは Organization の名前に置き換えます。

以下の例では、イメージのバージョン 2.5 をプッシュします。

docker push ghcr.io/NAMESPACE/IMAGE_NAME:2.5

パッケージを最初に公開する際のデフォルトの可視性はプライベートです。可視性の変更やアクセス許可の設定については、「パッケージのアクセス制御と可視性の設定」を参照してください。ユーザーインターフェイスまたはコマンドラインを使用して、公開済みのパッケージをリポジトリにリンクできます。詳しくは、「リポジトリのパッケージへの接続」を参照してください。

コマンドラインからコンテナーイメージをプッシュすると、そのイメージは既定ではリポジトリにリンクされません。これは、ghcr.io/octocat/my-repo:latest のように、リポジトリの名前に一致する名前空間でイメージにタグした場合でも当てはまります。

リポジトリをコンテナーパッケージに接続する最も簡単に方法は、${{secrets.GITHUB_TOKEN}} を利用してワークフローからパッケージを発行することです。ワークフローが含まれるリポジトリが自動的にリンクされるためです。同じ名前空間に以前、パッケージをプッシュしているが、そのパッケージをリポジトリに接続していない場合、パッケージをプッシュする許可は GITHUB_TOKEN に与えられません。

コマンドラインからイメージを発行するときにリポジトリを接続し、GitHub Actions ワークフローの使用時に適切なアクセス許可を GITHUB_TOKEN に確実に与えるため、ラベル org.opencontainers.image.source を Dockerfile に追加することをお勧めします。詳しくは、この記事の「コンテナーイメージのラベル付け」と「GitHub Actionsでのパッケージの公開とインストール」をご覧ください。

コンテナイメージをプルする

ダイジェストによるプル

常に同一のイメージを使用するため、digest SHA 値でプルするコンテナーイメージのバージョンを指定できます。

docker inspect または docker pull を使用してダイジェスト SHA 値を調べ、その SHA 値を Digest: の後にコピーします
```
docker inspect ghcr.io/NAMESPACE/IMAGE_NAME
```
NAMESPACE を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。
必要に応じてローカルでイメージを削除します。
```
docker rmi  ghcr.io/NAMESPACE/IMAGE_NAME:latest
```
イメージ名の後に @YOUR_SHA_VALUE を付けてコンテナーイメージをプルします。
```
docker pull ghcr.io/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs
```

名前によるプル

docker pull ghcr.io/NAMESPACE/IMAGE_NAME

NAMESPACE を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。

名前とバージョンによるプル

名前と 1.14.1 バージョンタグにより Docker CLI でイメージをプルする例を以下に示します。

$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:1.14.1
> 5e35bd43cf78: Pull complete
> 0c48c2209aab: Pull complete
> fd45dd1aad5a: Pull complete
> db6eb50c2d36: Pull complete
> Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1
> ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1

NAMESPACE を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。

名前と最新バージョンによるプル

$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:latest
> latest: Pulling from NAMESPACE/IMAGE_NAME
> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME:latest
> ghcr.io/NAMESPACE/IMAGE_NAME:latest

NAMESPACE を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。

コンテナイメージを構築する

以下の例では hello_docker イメージを構築します。

docker build -t hello_docker .

コンテナイメージにタグ付けする

タグ付けする Docker イメージの ID を調べます。

$ docker images
> REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
> ghcr.io/my-org/hello_docker         latest            38f737a91f39        47 hours ago        91.7MB
> hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB

イメージ ID を使用して、Docker イメージを任意のイメージ名とホスティング先でタグ付けします。
```
docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest
```

NAMESPACE を、イメージのスコープ指定先にしたい個人アカウントまたは Organization の名前に置き換えます。

コンテナーイメージのラベル付け

定義済みの注釈キーを使って、説明、ライセンス、ソースリポジトリなどのメタデータをコンテナーイメージに追加できます。サポートされているキーの値は、イメージのパッケージページに表示されます。

ほとんどのイメージでは、Docker ラベルを使用して注釈キーをイメージに追加できます。詳細については、Docker の公式ドキュメントの「LABEL」および opencontainers/image-spec リポジトリの「定義済みの注釈キー」を参照してください。

マルチアーキテクチャイメージの場合は、イメージのマニフェストの annotations フィールドに適切な注釈キーを追加することで、イメージに説明を追加できます。詳細については、「マルチアーキテクチャイメージへの説明の追加」を参照してください。

Container registryでは、次の注釈キーがサポートされています。

Key	説明
`org.opencontainers.image.source`	パッケージに関連付けられているリポジトリの URL。詳しくは、「リポジトリのパッケージへの接続」を参照してください。
`org.opencontainers.image.description`	512 文字に制限されたテキストのみの説明。この説明は、パッケージページのパッケージの名前の下に表示されます。
`org.opencontainers.image.licenses`	256 文字に制限された SPDX ライセンス識別子 ("MIT" など)。ライセンスは、パッケージページの [詳細] サイドバーに表示されます。詳細については、「SPDX ライセンス一覧」を参照してください。

Docker ラベルとしてキーを追加するには、Dockerfile の LABEL 命令を使用することをお勧めします。たとえば、ユーザー octocat が my-repo を所有していて、MIT ライセンスの条件に従ってイメージが配布されている場合は、次の行を Dockerfile に追加します。

LABEL org.opencontainers.image.source=https://github.com/octocat/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

注: リポジトリにリンクされているパッケージを公開した場合、パッケージは自動的にリンクされたリポジトリのアクセス許可を継承し、Organization によってアクセス許可の自動継承が無効にされていない限り、リンクされたリポジトリ内の GitHub Actions ワークフローは自動的にパッケージにアクセスできるようになります。詳しくは、「パッケージのアクセス制御と可視性の設定」を参照してください。

または、docker build コマンドを使用して、ビルド時にラベルをイメージに追加することもできます。

$ docker build \
 --label "org.opencontainers.image.source=https://github.com/octocat/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"

マルチアーキテクチャイメージへの説明の追加

マルチアーキテクチャイメージは、複数のアーキテクチャをサポートするイメージです。これは、1 つのマニフェスト内で、それぞれ異なるアーキテクチャをサポートするイメージの一覧を参照することによって機能します。

マルチアーキテクチャイメージのパッケージページに表示される説明は、イメージのマニフェストの annotations フィールドから取得されます。 Docker ラベルと同様に、注釈によってメタデータをイメージに関連付ける方法が提供され、定義済みの注釈キーがサポートされます。詳細については、opencontainers/image-spec リポジトリ内の「注釈」を参照してください。

マルチアーキテクチャイメージの説明を指定するには、次のように、マニフェストの annotations フィールドで org.opencontainers.image.description キーの値を設定します。

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

たとえば、次の GitHub Actions ワークフローステップでは、マルチアーチイメージをビルドしてプッシュします。 outputs パラメーターを使用すると、イメージの説明が設定されます。

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

- name: Build and push Docker image
  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=My multi-arch image

トラブルシューティング

Container registry には、レイヤーごとに 10 GB のサイズ制限があります。
Container registry には、アップロードのタイムアウト制限が 10 分あります。