Working with the Container registry

About the Container registry

Container registry 将容器映像存储在组织或个人帐户中，并允许你将映像与存储库相关联。 可以选择是从存储库继承权限，还是独立于存储库设置精细权限。 你也可以匿名访问公共容器映像。

About Container registry support

The Container registry currently supports the following container image formats:

• Docker Image Manifest V2, Schema 2
• Open Container Initiative (OCI) Specifications

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. If your workflow is using a personal access token (PAT) to authenticate to a registry, then we highly recommend you update your workflow to use the GITHUB_TOKEN.

For guidance on updating your workflows that authenticate to a registry with a personal access token, see "Upgrading a workflow that accesses a registry using a PAT."

For more information about the GITHUB_TOKEN, see "Authentication in a workflow."

For more information about the best practises when using a registry in actions, see "Security hardening for GitHub Actions."

1. 针对要完成的任务，新创具有适当作用域的个人访问令牌 (PAT)。 如果您的组织需要 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 上的 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