使用容器注册表

您可以在容器注册表中存储和管理 Docker 和 OCI 镜像。

谁可以使用此功能？

GitHub Packages 可用于 GitHub Free、GitHub Pro、GitHub Free for organizations、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 3.0 或更高版本。


对于使用旧版每个存储库计划的帐户拥有的私有存储库，GitHub Packages 不可用。此外，使用旧版每个存储库计划的帐户无法访问支持细粒度权限的注册表，因为这些帐户按存储库计费。有关支持细粒度权限的注册表列表，请参阅“GitHub Packages 的权限”。有关更多信息，请参阅“GitHub 的计划”。

本文内容

关于容器注册表

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

关于容器注册表支持

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

在安装或发布 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 删除和恢复软件包的功能目前处于公开预览阶段，可能会发生更改。

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

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

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

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

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

  1. 创建一个新的个人访问令牌（经典），其中包含您要完成的任务的相应作用域。如果您的组织需要 SSO，则必须为您的新令牌启用 SSO。

    注意

    默认情况下，当您在用户界面中为个人访问令牌（经典）选择 write:packages 作用域时，repo 作用域也将被选中。repo 作用域提供了不必要且广泛的访问权限，我们建议您尤其避免在 GitHub Actions 工作流中使用它。有关更多信息，请参阅“GitHub Actions 的安全强化”。作为解决方法，您可以使用此 URL 在用户界面中仅为您的个人访问令牌（经典）选择 write:packages 作用域：https://github.com/settings/tokens/new?scopes=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.licensesSPDX 许可证标识符，例如“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

注意

如果您发布一个链接到代码库的包，则该包会自动继承链接代码库的访问权限，并且链接代码库中的 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存储库中的注释。

要为多架构镜像提供描述，请在清单的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 分钟的超时限制。