Skip to main content

Working with the Container registry

You can store and manage Docker and OCI images in the Container registry, which uses the package namespace https://ghcr.io.

GitHub Packages は、GitHub Free、GitHub Pro、Organization の GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0 以降、GitHub AE で利用できます。
GitHub Packagesは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 また、レガシーのリポジトリごとのプランを使っているアカウントは、リポジトリごとに課金される Container registry にはアクセスできません。 詳細については、「GitHub's products」を参照してください。

About the Container registry

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

About Container registry support

The Container registry currently supports the following container image formats:

When installing or publishing a Docker image, the Container registry supports foreign layers, such as Windows images.

Authenticating to the Container registry

To authenticate to the Container registry (ghcr.io) within a GitHub Actions workflow, use the GITHUB_TOKEN for the best security and experience. お使いのワークフローで個人アクセス トークン (PAT) を使用してレジストリの認証を受ける場合、GITHUB_TOKEN を使用するようにワークフローを更新することを強くお勧めします。

個人用アクセス トークンでレジストリの認証を行うワークフローの更新についてのガイダンスは、「PAT を使ってレジストリにアクセスするワークフローをアップグレードする」をご覧ください。

GITHUB_TOKEN の詳細については「ワークフローで認証する」を参照してください。

アクションでレジストリを使用するときのベスト プラクティスについて詳しくは「GitHub Actions のセキュリティ強化」をご覧ください。

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

    注: 既定では、ユーザー インターフェイスで個人用アクセス トークン (PAT) の write:packages スコープを選択すると、repo スコープも選択されます。 repo スコープは不要に広いアクセス権を提供するので、特に GitHub Actions のワークフローでの利用は避けることをお勧めします。 詳細については、「GitHub Actions のセキュリティ強化」を参照してください。 回避策として、URL https://github.com/settings/tokens/new?scopes=write:packages のユーザー インターフェイスで自分の PAT だけの write:packages スコープを選択できます。

    • read:packages スコープを選択すると、コンテナー イメージがダウンロードされ、そのメタデータが読み取られます。
    • write:packages スコープを選択すると、コンテナー イメージがダウンロードされ、アップロードされ、そのメタデータが読み書きされます。
    • delete:packages スコープを選択すると、コンテナー イメージが削除されます。

    詳細については、コマンド ライン用の個人アクセス トークンの使用に関するページを参照してください。

  2. PATを保存してください。 PATは環境変数として保存することをおすすめします。

    $ export CR_PAT=YOUR_TOKEN
  3. コンテナーの種類に CLI を使用し、ghcr.io で Container registry サービスにサインインします。

    $ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
    > Login Succeeded

Pushing container images

This example pushes the latest version of IMAGE_NAME.

$ docker push ghcr.io/OWNER/IMAGE_NAME:latest

This example pushes the 2.5 version of the image.

$ docker push ghcr.io/OWNER/IMAGE_NAME:2.5

When you first publish a package, the default visibility is private. To change the visibility or set access permissions, see "Configuring a package's access control and visibility."

Pulling container images

Pull by digest

To ensure you're always using the same image, you can specify the exact container image version you want to pull by the digest SHA value.

  1. To find the digest SHA value, use docker inspect or docker pull and copy the SHA value after Digest:

    $ docker inspect ghcr.io/OWNER/IMAGE_NAME
  2. Remove image locally as needed.

    $ docker rmi  ghcr.io/OWNER/IMAGE_NAME:latest
  3. Pull the container image with @YOUR_SHA_VALUE after the image name.

    $ docker pull ghcr.io/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

Pull by name

$ docker pull ghcr.io/OWNER/IMAGE_NAME

Pull by name and version

Docker CLI example showing an image pulled by its name and the 1.14.1 version tag:

$ docker pull ghcr.io/OWNER/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/orgname/image-name/release:1.14.1
  > ghcr.io/orgname/image-name/release:1.14.1

Pull by name and latest version

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

Building container images

This example builds the hello_docker image:

$ docker build -t hello_docker .

Tagging container images

  1. Find the ID for the Docker image you want to tag.

    $ docker images
    > REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
    > ghcr.io/my-org/hello_docker         latest              38f737a91f39        47 hours ago        91.7MB
    > ghcr.io/my-username/hello_docker    latest              38f737a91f39        47 hours ago        91.7MB
    > hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB
  2. Tag your Docker image using the image ID and your desired image name and hosting destination.

    $ docker tag 38f737a91f39 ghcr.io/OWNER/NEW_IMAGE_NAME:latest

Labelling container images

You can use Docker labels to add metadata including a description, a license, and a source repository to your container image. For more information on Docker labels, see LABEL in the official Docker documentation and Pre-Defined Annotation Keys in the opencontainers/image-spec repository.

The following labels are supported in the Container registry. Supported labels will appear on the package page for the image.

LabelDescription
org.opencontainers.image.sourceThe URL of the repository associated with the package. For more information, see "Connecting a repository to a package."
org.opencontainers.image.descriptionA text-only description limited to 512 characters. This description will appear on the package page, below the name of the package.
org.opencontainers.image.licensesAn SPDX license identifier such as "MIT," limited to 256 characters. The license will appear on the package page, in the "Details" sidebar. For more information, see SPDX License List.

To add labels to an image, we recommend using the LABEL instruction in your Dockerfile. For example, if you're the user monalisa and you own my-repo, and your image is distributed under the terms of the MIT license, you would add the following lines to your Dockerfile:

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

Alternatively, you can add labels to an image at buildtime with the docker build command.

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