Note
現在、Container registry は GitHub Enterprise Server に対して ベータ 段階であり、変更される可能性があります。
Container registry を使うには、GitHub Packages と Subdomain Isolation の両方を有効にする必要があります。 詳しくは、「コンテナレジストリの利用」を参照してください。
Container registry について
Container registry は、Organization または個人アカウント内にコンテナー イメージを格納し、イメージをリポジトリに関連付けることができます。 権限をリポジトリから継承するか、リポジトリとは別に細かい権限を設定するかを選ぶことができます。 パブリック コンテナー イメージに匿名でアクセスすることもできます。
GitHub Enterprise Server で Container registry を使用するには、サイト管理者が最初にインスタンスの GitHub Packages を構成してからサブドメインの分離を有効にする必要があります。 詳細については、「Enterprise 向けの GitHub Packages を使い始める」および「Subdomain Isolationの有効化」を参照してください。
Container registryサポートについて
現在のところ、Container registry では以下のコンテナフォーマットをサポートしています。
Dockerイメージをインストールあるいは公開する際には、Container registryはWindowsイメージのような外部レイヤーもサポートします。
Container registryでの認証
GitHub Packages では、personal access token (classic)を使用した認証のみがサポートされています。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。
非公開パッケージ、内部パッケージ、公開パッケージを発行、インストール、削除するには、アクセス トークンが必要です。
personal access token (classic) を使って、GitHub Packages または GitHub Enterprise Server 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でのパッケージの公開とインストール」をご覧ください。
Note
REST API を使ってパッケージを削除および復元する GitHub Actions ワークフローの機能は、現在 ベータ 段階であり、変更される可能性があります。
トークンにパッケージに対する admin
アクセス許可がある場合、GitHub Actions ワークフローで GITHUB_TOKEN
を使用し、REST API を使ってパッケージを削除または復元できます。 ワークフローを使ってパッケージを発行するリポジトリと、パッケージに明示的に接続したリポジトリには、リポジトリ内のパッケージに対する admin
アクセス許可が自動的に付与されます。
GITHUB_TOKEN
について詳しくは、「自動トークン認証」をご覧ください。 アクションでレジストリを使うときのベスト プラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。
また、GitHub Actions に対して、パッケージにアクセス許可を個別に付与することもできます。 詳細については、「パッケージのアクセス制御と可視性の設定」および「パッケージのアクセス制御と可視性の設定」を参照してください。
personal access token (classic)
で認証を行う
次の例の HOSTNAME
を、お使いの GitHub Enterprise Server インスタンス のホスト名または IP アドレスに置き換えてください。
GitHub Packages では、personal access token (classic)を使用した認証のみがサポートされています。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。
-
実行したいタスクに対して適切なスコープを持つ新しい personal access token (classic) を作成してください。 OrganizationがSSOを必須としている場合は、新しいトークンでSSOを有効化しなければなりません。
Note
既定では、ユーザー インターフェイスで personal access token (classic) に対して
write:packages
スコープを選ぶと、repo
スコープも選ばれます。repo
スコープは不要に広いアクセス権を提供するので、特に GitHub Actions ワークフローでの利用は避けることをお勧めします。 詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。 回避策として、URLhttps://HOSTNAME/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 を使用し、
containers.HOSTNAME
で Container registry サービスにサインインします。$ echo $CR_PAT | docker login containers.HOSTNAME -u USERNAME --password-stdin > Login Succeeded
コンテナイメージをプッシュする
この例では、最新バージョンの IMAGE_NAME
をプッシュします。
docker push containers.HOSTNAME/NAMESPACE/IMAGE_NAME:latest
NAMESPACE
を、イメージのスコープ指定先にしたい個人アカウントまたは Organization の名前に置き換えます。
以下の例では、イメージのバージョン 2.5
をプッシュします。
docker push containers.HOSTNAME/NAMESPACE/IMAGE_NAME:2.5
パッケージを最初に公開する際のデフォルトの可視性はプライベートです。 可視性の変更やアクセス許可の設定については、「パッケージのアクセス制御と可視性の設定」を参照してください。 ユーザー インターフェイスまたはコマンド ラインを使用して、公開済みのパッケージをリポジトリにリンクできます。 詳しくは、「リポジトリのパッケージへの接続」を参照してください。
コマンド ラインからコンテナー イメージをプッシュすると、そのイメージは既定ではリポジトリにリンクされません。 これは、containers.github.companyname.com/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 containers.HOSTNAME/NAMESPACE/IMAGE_NAME
NAMESPACE
を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。 -
必要に応じてローカルでイメージを削除します。
docker rmi containers.HOSTNAME/NAMESPACE/IMAGE_NAME:latest
-
イメージ名の後に
@YOUR_SHA_VALUE
を付けてコンテナー イメージをプルします。docker pull containers.HOSTNAME/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs
名前によるプル
docker pull containers.HOSTNAME/NAMESPACE/IMAGE_NAME
NAMESPACE
を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。
名前とバージョンによるプル
名前と 1.14.1
バージョン タグにより Docker CLI でイメージをプルする例を以下に示します。
$ docker pull containers.HOSTNAME/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 containers.HOSTNAME/NAMESPACE/IMAGE_NAME/release:1.14.1
> containers.HOSTNAME/NAMESPACE/IMAGE_NAME/release:1.14.1
NAMESPACE
を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。
名前と最新バージョンによるプル
$ docker pull containers.HOSTNAME/NAMESPACE/IMAGE_NAME:latest
> latest: Pulling from NAMESPACE/IMAGE_NAME
> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
> Status: Downloaded newer image for containers.HOSTNAME/NAMESPACE/IMAGE_NAME:latest
> containers.HOSTNAME/NAMESPACE/IMAGE_NAME:latest
NAMESPACE
を、イメージのスコープ指定先にする個人アカウントまたは Organization の名前に置き換えます。
コンテナイメージを構築する
以下の例では hello_docker
イメージを構築します。
docker build -t hello_docker .
コンテナイメージにタグ付けする
-
タグ付けする Docker イメージの ID を調べます。
$ docker images > REPOSITORY TAG IMAGE ID CREATED SIZE > containers.HOSTNAME/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 containers.HOSTNAME/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://HOSTNAME/octocat/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT
または、docker build
コマンドを使用して、ビルド時にラベルをイメージに追加することもできます。
$ docker build \
--label "org.opencontainers.image.source=https://HOSTNAME/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 分あります。