使用容器仓库

关于容器仓库

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

关于容器注册表支持

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

• Docker 镜像清单 V2，模式 2
• 开放容器倡议 (OCI) 规范

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

对容器注册表的身份验证

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

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

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

• GITHUB_TOKEN 发布与工作流存储库关联的包。
• 具有至少 read:packages 范围的个人访问令牌（经典）来安装与其他私有存储库关联的包（GITHUB_TOKEN 无法访问）。

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

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

如果令牌对包具有 admin 权限，您可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN 使用 REST API 删除或恢复包。使用工作流发布包的存储库以及您已明确连接到包的存储库会自动获得对存储库中包的 admin 权限。

有关GITHUB_TOKEN的更多信息，请参阅“自动令牌身份验证”。有关在操作中使用注册表的最佳实践的更多信息，请参阅“GitHub Actions 安全加固”。

您也可以选择独立为 GitHub Codespaces 和 GitHub Actions 提供对包的访问权限。有关更多信息，请参阅“配置包的访问控制和可见性”和“配置包的访问控制和可见性”。

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

1. 创建一个新的个人访问令牌（经典），并为要执行的任务提供适当的范围。如果您的组织需要 SSO，则必须为您的新令牌启用 SSO。

   注意：默认情况下，当您在用户界面中为个人访问令牌（经典）选择write:packages范围时，repo范围也会被选中。repo范围提供了不必要的和广泛的访问权限，我们建议您特别避免在 GitHub Actions 工作流程中使用它。有关更多信息，请参阅“GitHub Actions 安全加固”。作为解决方法，您可以在用户界面中使用此 URL：https://github.com/settings/tokens/new?scopes=write:packages，仅为您的个人访问令牌（经典）选择write:packages范围。

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

   有关更多信息，请参阅“管理您的个人访问令牌”。

2. 保存您的个人访问令牌（经典）。我们建议将您的令牌保存为环境变量。

   export CR_PAT=YOUR_TOKEN
   

3. 使用您的容器类型的 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 具有适当的权限，建议您将标签 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 替换为您要将镜像范围限定到的个人帐户或组织的名称。

按名称和版本拉取

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 .

标记容器镜像

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` 字段中来添加镜像描述。有关更多信息，请参阅“为多架构镜像添加描述”。

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

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

要将键作为 Docker 标签添加，我们建议您在 `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

或者，您可以在构建时使用 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 存储库中的 注释。

要为多体系结构镜像提供描述，请在清单的 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 分钟。