使用容器注册表

关于容器注册表

容器注册表将在您的组织或个人账户中存储容器镜像，并允许您将镜像关联到仓库。您可以选择继承仓库的权限，或独立于仓库设置细粒度权限。您还可以匿名访问公共容器镜像。

关于容器注册表支持

容器注册表目前支持以下容器镜像格式

在安装或发布 Docker 镜像时，容器注册表支持外部层（如 Windows 镜像）。

对容器注册表进行身份验证

注意

GitHub Packages 仅支持使用个人访问令牌（经典版）进行身份验证。欲了解更多信息，请参阅管理您的个人访问令牌。

您需要访问令牌才能发布、安装和删除私有、内部以及公共软件包。

您可以使用个人访问令牌（经典版）对 GitHub Packages 或 GitHub API 进行身份验证。创建个人访问令牌（经典版）时，可根据需要为令牌分配不同的范围。有关个人访问令牌（经典版）的软件包相关范围的更多信息，请参阅 GitHub Packages 权限概述。

要在 GitHub Actions 工作流中对 GitHub Packages 注册表进行身份验证，您可以使用

GITHUB_TOKEN 来发布与工作流仓库关联的软件包。
使用至少具备 read:packages 范围的个人访问令牌（经典版）来安装与其他私有仓库关联的软件包（如果仓库被授予读取软件包的权限，也可以使用 GITHUB_TOKEN。参见配置软件包的访问控制和可见性）。

在 GitHub Actions 工作流中进行身份验证

此注册表支持细粒度权限。对于支持细粒度权限的注册表，如果您的 GitHub Actions 工作流使用个人访问令牌对注册表进行身份验证，我们强烈建议您将工作流更新为使用 GITHUB_TOKEN。有关使用个人访问令牌对注册表进行身份验证的工作流更新指南，请参阅使用 GitHub Actions 发布和安装软件包。

注意

GitHub Actions 工作流使用 REST API 删除和恢复软件包的功能目前处于公开预览阶段，可能会有变更。

您可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN 删除或恢复软件包（通过 REST API），前提是该令牌对软件包拥有 admin 权限。使用工作流发布软件包的仓库，以及您已显式连接到软件包的仓库，都会自动获得该仓库中软件包的 admin 权限。

有关 GITHUB_TOKEN 的更多信息，请参阅在工作流中使用 GITHUB_TOKEN 进行身份验证。有关在 Actions 中使用注册表的最佳实践，请参阅安全使用参考。

您还可以为 GitHub Codespaces 和 GitHub Actions 分别独立设置软件包的访问权限。有关详细信息，请参阅配置软件包的访问控制和可见性和配置软件包的访问控制和可见性。

使用个人访问令牌（经典版）进行身份验证

注意

GitHub Packages 仅支持使用个人访问令牌（经典版）进行身份验证。欲了解更多信息，请参阅管理您的个人访问令牌。

为您想要完成的任务创建一个具有相应作用域的个人访问令牌（经典版）。如果您的组织要求 SSO，您必须为新令牌启用 SSO。

注意

默认情况下，当您在用户界面中为个人访问令牌（经典版）选择 write:packages 作用域时，repo 作用域也会被选中。repo 作用域提供了不必要且范围过大的访问权限，我们特别建议在 GitHub Actions 工作流中避免使用。更多信息，请参阅安全使用参考。作为变通方法，您可以在用户界面中仅选择 write:packages 作用域，使用以下 URL：https://github.com/settings/tokens/new?scopes=write:packages。
- 选择 read:packages 作用域可下载容器镜像并读取其元数据。
- 选择 write:packages 作用域可下载和上传容器镜像，并读取和写入其元数据。
- 选择 delete:packages 作用域可删除容器镜像。
有关更多信息，请参阅管理个人访问令牌。
保存您的个人访问令牌（经典版）。我们建议将令牌保存为环境变量。
```
export CR_PAT=YOUR_TOKEN
```

使用适用于您容器类型的 CLI 登录位于 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 Actions 工作流中使用的 GITHUB_TOKEN 具有适当的权限，我们建议在 Dockerfile 中添加标签 org.opencontainers.image.source。更多信息，请参阅本文中的“标记容器镜像”以及“使用 GitHub Actions 发布和安装软件包”。

拉取容器镜像

按摘要拉取

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

要获取 digest SHA 值，可使用 docker inspect 或 docker pull，并复制 Digest: 后面的 SHA 值。
```
docker inspect ghcr.io/NAMESPACE/IMAGE_NAME
```
将 NAMESPACE 替换为镜像所属的个人账户或组织的名称。

根据需要在本地删除镜像。

docker rmi ghcr.io/NAMESPACE/IMAGE_NAME:latest

在镜像名称后添加 @YOUR_SHA_VALUE 以拉取容器镜像。

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

按名称拉取

docker pull ghcr.io/NAMESPACE/IMAGE_NAME

将 NAMESPACE 替换为镜像所属的个人账户或组织的名称。

按名称和版本拉取

Docker CLI 示例，展示通过名称及 1.14.1 版本标签拉取镜像

$ 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 .

标记容器镜像

找到您想要标记的 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

使用镜像 ID 以及您期望的镜像名称和托管目标来标记 Docker 镜像。
```
docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest
```

将 NAMESPACE 替换为您希望为其设置范围的个人账户或组织的名称。

标记容器镜像

您可以使用预定义的注解键为容器镜像添加元数据，包括描述、许可证和源代码仓库。受支持键的值将显示在该镜像的包页面上。

对于大多数镜像，您可以使用 Docker label 将注解键添加到镜像中。更多信息，请参阅官方 Docker 文档中的 LABEL，以及 opencontainers/image-spec 仓库中的预定义注解键。

对于多架构镜像，您可以通过在镜像清单的 annotations 字段中添加相应的注解键来为镜像添加描述。更多信息，请阅为多架构镜像添加描述。

容器注册表支持以下注解键。

键	描述
`org.opencontainers.image.source`	与软件包关联的仓库的 URL。更多信息，请参阅将仓库连接到软件包。
`org.opencontainers.image.description`	仅限文本的描述，最多 512 个字符。该描述将显示在软件包页面上，位于软件包名称下方。
`org.opencontainers.image.licenses`	SPDX 许可证标识符，例如 “MIT”，最多 256 个字符。许可证将显示在软件包页面的 “详情” 侧栏中。更多信息，请参阅 SPDX 许可证列表。

要将键添加为 Docker label，我们建议在 Dockerfile 中使用 LABEL 指令。例如，如果您是用户 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 labels 类似，annotations 为镜像提供关联元数据的方式，并支持预定义的注解键。更多信息，请参阅 opencontainers/image-spec 仓库中的 Annotations。

要为多架构镜像提供描述，请在清单的 annotations 字段中为 org.opencontainers.image.description 键设置值，如下所示。

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

例如，以下 GitHub Actions 工作流步骤构建并推送多架构镜像。outputs 参数用于设置镜像的描述。

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

- 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

故障排除

容器注册表对每个层的大小限制为 10 GB。
容器注册表对上传的超时时间限制为 10 分钟。

本文内容