使用容器注册表

可以在 . Container registry. 中存储和管理 Docker 和 OCI 映像。

谁可以使用此功能？

Enterprise Managed Users 可以发布到组织的命名空间。 这些用户无法将包发布到其帐户的命名空间中，因为没有个人存储分配。 有关 Enterprise Managed Users 的更多信息，请参阅 关于 Enterprise Managed Users。

在本文中

关于 Container registry

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

Container registry 的 URL

如果您在 GitHub 访问 GitHub.com，则会将包发布到 ghcr.io。 本文中的示例使用此 URL。

如果您在另一个域名上访问GitHub，例如 octocorp.ghe.com，请将“ghcr.io”替换为https://containers.SUBDOMAIN.ghe.com，其中 SUBDOMAIN 是贵企业的唯一子域名。

关于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 Packages 工作流程内向 GitHub Actions 注册表验证，您可以使用：

  • 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_TOKEN 进行身份验证。 有关在操作中使用注册表时的最佳做法的详细信息，请参阅 被入侵的运行器。

还可以选择为 GitHub Codespaces 和 GitHub Actions 单独授予对包的访问权限。 有关详细信息，请参阅 配置包的访问控制和可见性 和 配置包的访问控制和可见性。

使用personal access token (classic)进行身份验证

注意

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息，请参阅“管理个人访问令牌”。

  1. 创建一个新的 personal access token (classic)，并为其设置适合您要完成的任务的范围。 如果您的组织需要 SSO，则必须为新令牌启用 SSO。

    注意

    默认情况下，当您在用户界面中为 personal access token (classic) 选择 write:packages 范围时，系统也会同时选中 repo 范围。 repo 权限范围授予了不必要且过于宽泛的访问权限，我们特别建议你避免将其用于 GitHub Actions 工作流。 有关详细信息，请参阅“被入侵的运行器”。 作为一种变通方法，你可以通过以下 URL 在用户界面中仅为你的 personal access token (classic) 选择 write:packages 作用域：https://github.com/settings/tokens/new?scopes=write:packages

    • 选择 read:packages 范围以下载容器映像并读取其元数据。
    • 选择 write:packages 范围以下载和上传容器映像并读写其元数据。
    • 选择 delete:packages 范围以删除容器映像。

    有关详细信息，请参阅“管理个人访问令牌”。

  2. 保存你的 personal access token (classic)。 建议将令牌保存为环境变量。

    export CR_PAT=YOUR_TOKEN

  3. 使用适用于您的容器类型的 CLI，登录到位于 Container registry 的 ghcr.io 服务。

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

推送容器映像

此示例推送最新版本的 IMAGE_NAME。

docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest

将 NAMESPACE 替换为你希望作为映像限定范围的个人帐户或组织的名称。

此示例推送映像的 2.5 版本。

docker push ghcr.io/NAMESPACE/IMAGE_NAME:2.5

首次发布包时，默认可见性是私有的。 若要更改可见性或设置访问权限，请参阅 配置包的访问控制和可见性。 可以使用用户界面或命令行将已发布的包链接到存储库。 有关详细信息，请参阅“将仓库连接到软件包”。

从命令行推送容器映像时，默认情况下，该映像不会链接到存储库。 即使使用与存储库名称匹配的命名空间（例如 ghcr.io/octocat/my-repo:latest）标记映像，也是如此。

将存储库连接到容器包的最简单方法是使用 ${{secrets.GITHUB_TOKEN}} 从工作流发布包，因为包含工作流的存储库会自动链接。 请注意，如果之前已将包推送到同一命名空间，但尚未将包连接到存储库，则 GITHUB_TOKEN 将无权推送包。

要在使用命令行发布镜像时连接存储库，并确保你的 GITHUB_TOKEN 在使用 GitHub Actions 工作流时具有适当的权限，建议将标签 org.opencontainers.image.source 添加到 Dockerfile。 有关详细信息，请参阅本文中的“标记容器映像”和“使用 GitHub Actions 发布和安装包”。

拉取容器映像

通过摘要拉取

为确保始终使用相同的映像，可以通过 digest SHA 值指定要拉取的确切容器映像版本。

  1. 若要查找摘要 SHA 值，请使用 docker inspect 或 docker pull 并在 Digest: 之后复制 SHA 值

    docker inspect ghcr.io/NAMESPACE/IMAGE_NAME

    将 NAMESPACE 替换为要作为映像限定范围的个人帐户或组织的名称。

  2. 按需要在本地删除映像。

    docker rmi ghcr.io/NAMESPACE/IMAGE_NAME:latest

  3. 在映像名称后添加 @YOUR_SHA_VALUE 以拉取容器映像。

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

按名称拉取

docker pull ghcr.io/NAMESPACE/IMAGE_NAME

将 NAMESPACE 替换为要作为映像限定范围的个人帐户或组织的名称。

按名称和版本拉取

显示按名称和 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 替换为要作为映像限定范围的个人帐户或组织的名称。

按名称和最新版本拉取

$ 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 替换为要作为映像限定范围的个人帐户或组织的名称。

构建容器镜像

此示例生成 hello_docker 映像：

docker build -t hello_docker .

给容器镜像打标签

  1. 找到要标记的 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

  2. 使用映像 ID 以及所需的映像名称和托管目标标记 Docker 映像。

    docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest

将 NAMESPACE 替换为你希望作为映像限定范围的个人帐户或组织的名称。

标记容器映像

可以使用预定义的注释键向容器映像添加元数据，包括说明、许可证和源存储库。 受支持的键的值将显示在该镜像的软件包页面上。

对于大多数映像，可以使用 Docker 标签将注释密钥添加到映像。 有关详细信息，请参阅 Docker 官方文档中的“LABEL”和 存储库中的“opencontainers/image-spec”。

对于多架构映像，可以通过将适当的注释密钥添加到映像清单中的 annotations 字段来为映像添加说明。 有关详细信息，请参阅向多架构映像添加说明。

Container registry 中支持以下注释键。

密钥说明
org.opencontainers.image.source与包关联的存储库的 URL。 有关详细信息，请参阅“将仓库连接到软件包”。
org.opencontainers.image.description纯文本说明，限制在 512 个字符以内。 此说明将显示在包页中的包名称下方。
org.opencontainers.image.licensesSPDX 许可证标识符，如“MIT”，限制在 256 个字符以内。 许可证将显示在包页的“详细信息”边栏中。 有关详细信息，请参阅 SPDX 许可证列表。

若要添加密钥作为 Docker 标签，建议在 LABEL 中使用 Dockerfile 指令。 例如，如果你是用户 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

注意

如果发布链接到存储库的包，该包会自动继承链接存储库的访问权限，链接存储库中的 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"

向多架构映像添加说明

多架构映像是支持多种体系结构的映像。 它的原理是在单一清单中引用一系列映像，其中每个映像都支持不同的体系结构。

多架构映像的“包”页面中的说明是从映像清单中的 annotations 字段获取的。 与 Docker 标签一样，注释提供了一种将元数据与映像相关联的方法，并支持预定义的注释密钥。 有关详细信息，请参阅 注释 在 opencontainers/image-spec 存储库中。

若要为多架构映像提供说明，请在清单的 org.opencontainers.image.description 字段中为 annotations 键设置一个值，如下所示。

"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 分钟。