Migrating to the Container registry from the Docker registry

Key differences between the コンテナレジストリ and the Docker registry

The コンテナレジストリ supersedes the existing GitHub Packages Docker registry and is optimized to support some of the unique needs of containers.

With the コンテナレジストリ you can:

• Store container images within your organization and user account, rather than a repository.
• Set granular permissions and visibility independently of repository permissions and visibility.
• Access public container images anonymously.

Billing changes

During the コンテナレジストリ beta, both the new コンテナレジストリ and the existing GitHub Packages Docker registry are free of charge. For more information about the GitHub Packages Docker registry, see "Working with the Docker registry."

After the beta, the same billing and storage rates that other GitHub Packages registries use will apply to the コンテナレジストリ. For more information, see "About billing for GitHub Packages."

Domain changes

The domain for the コンテナレジストリ is ghcr.io.

Authenticating to the コンテナレジストリ

You will need to authenticate to the コンテナレジストリ with the base URL ghcr.io. We recommend creating a new access token for using the コンテナレジストリ.

PATはアカウントに対する広汎なアクセスを許可できます。 コンテナレジストリでの認証のためのPATを作成する際には、必要なread:packages、write:packages、delete:packagesスコープだけを選択すべきです。

GitHub Actionsワークフロー内でコンテナレジストリの認証を受けるには、最善のセキュリティと体験のためにGITHUB_TOKENを使ってください。

個人アクセストークンでghcr.ioの認証を受けるワークフローの更新に関するガイダンスとしては、「ghcr.ioにアクセスするワークフローのアップグレード」を参照してください。

コンテナレジストリは、ワークフロー内での容易でセキュアな認証のためにGITHUB_TOKENをサポートするようになりました。 ワークフローがghcr.ioでの認証のために個人アクセストークン（PAT）を使っているなら、GITHUB_TOKENを使うようにワークフローを更新することを強くおすすめします。

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

ベータの期間にアクションでコンテナレジストリを使いたい場合は、「GitHub Actionsのセキュリティ強化」にあるPATのセキュリティベストプラクティスに従ってください。

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

   ノート: デフォルトでは、ユーザインターフェース内で個人アクセストークン（PAT）に対してwrite:packagesスコープを選択すると、repoスコープも選択されます。 repoは不要に広いアクセス権を提供するので、特にGitHub Actionsのワークフローでの利用は避けることをおすすめします。 詳しい情報については「GitHub Actionsのためのセキュリティ強化」を参照してください。 回避策として、以下のURLでユーザインターフェース内でPATにwrite:packagesスコープだけを選択することができます。 https://github.com/settings/tokens/new?scopes=write:packages

   • コンテナイメージをダウンロードし、そのメタデータを読むためにはread:packagesスコープを選択してください。
   • コンテナイメージのダウンロードとアップロード、及びそのメタデータの読み書きのためには、write:packagesスコープを選択してください。
   • コンテナイメージを削除するにはdelete:packagesスコープを選択してください。

   詳しい情報についてはコマンドラインのための個人のアクセストークンの作成を参照してください。

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

   $ export CR_PAT=YOUR_TOKEN

3. コンテナタイプにあったCLIを利用して、 ghcr.ioにあるコンテナレジストリサービスにサインインしてください。

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

Migrating a Docker image using the Docker CLI

To move Docker images that you host on GitHub Packages Docker registry, you must republish the images to コンテナレジストリ. We recommend republishing your existing Docker images using the command line on your local machine.

1. Sign in to the Docker registry using a temporary PAT with at least the read:packages scope. This PAT will only be used to sign in to the Docker registry to pull down images and can be deleted afterward.

   $ echo $READ_PACKAGES_TOKEN | docker login docker.pkg.github.com -u USERNAME --password-stdin

2. Pull down the image you'd like to migrate, replacing OWNER with the name of the user or organization account that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image, VERSION with tag for the image you want to install. For example, docker pull docker.pkg.github.com/octo-org/octoshift/octoshift:latest pulls the latest tag of the octoshift/octoshift image in the octo-org organization.

   $ docker pull docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION

3. Re-tag the image with the new domain and a new image name. For more information, see "Docker tag" in the Docker documentation. Use the same URL that you used in the previous step for the SOURCE URL. Replace the TARGET_OWNER with the user or organization that you are migrating the container image to and replace the TARGET_IMAGE_NAME with the new コンテナレジストリ image name.

   $ docker tag docker.pkg.github.com/SOURCE_OWNER/SOURCE_REPOSITORY/SOURCE_IMAGE_NAME:VERSION ghcr.io/TARGET_OWNER/TARGET_IMAGE_NAME:VERSION

4. Sign in to the new コンテナレジストリ. We recommend creating a new PAT limited to the read:packages and write:packages scopes since you no longer need the repo scope and your previous PAT may not have the write:packages scope.

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

5. Push your re-tagged image to the コンテナレジストリ.

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

Updating your GitHub Actions workflow

If you have a GitHub Actions workflow that uses a Docker image from the GitHub Packages Docker registry, you may want to update your workflow to the コンテナレジストリ to allow for anonymous access for public container images, finer-grain access permissions, and better storage and bandwidth compatibility for containers.

1. Migrate your Docker images to the new コンテナレジストリ at ghcr.io. For an example, see "Migrating a Docker image using the Docker CLI."

2. In your GitHub Actions workflow file, update the package url from https://docker.pkg.github.com to ghcr.io.

3. Add your new コンテナレジストリ authentication personal access token (PAT) as a GitHub Actions secret. The コンテナレジストリ does not support using GITHUB_TOKEN for your PAT so you must use a different custom variable, such as CR_PAT. For more information, see "Creating and storing encrypted secrets."

4. In your GitHub Actions workflow file, update the authentication PAT by replacing your Docker registry PAT (${{ secrets.GITHUB_TOKEN }}) with a new variable for your コンテナレジストリ PAT, such as ${{ secrets.CR_PAT }}.

Example of updated workflow

If part of your workflow accessed a Docker image hosted by the Docker registry like this:

echo ${{ secrets.GITHUB_TOKEN }} | docker login https://docker.pkg.github.com -u $GITHUB_ACTOR --password-stdin
docker pull docker.pkg.github.com/github/octoshift/octoshift:latest
docker build . --tag docker.pkg.github.com/github/octoshift/octoshift:$GITHUB_SHA --cache-from docker.pkg.github.com/github/octoshift/octoshift:latest
docker push docker.pkg.github.com/github/octoshift/octoshift:$GITHUB_SHA

Then you'll need to update your workflow with the new コンテナレジストリ URL and PAT like this:

# new login with new container registry url and PAT
echo ${{ secrets.CR_PAT }} | docker login ghcr.io -u $GITHUB_ACTOR --password-stdin
# new container registry urls added
docker pull ghcr.io/github/octoshift:latest
docker build . --tag ghcr.io/github/octoshift:$GITHUB_SHA --cache-from ghcr.io/github/octoshift:latest
docker push ghcr.io/github/octoshift:$GITHUB_SHA