我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

迁移到 Docker 映像的 GitHub Container Registry

如果您已经使用 GitHub Packages Docker 注册表来存储 Docker 映像,可以迁移到新的 container registry。

GitHub Packages 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 2.22 和 GitHub One。


GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 GitHub Packages 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 For more information, see "[GitHub's products](/articles/github-s-products)."

本文内容

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。

GitHub Container Registry 与 Docker 软件包注册表之间的主要差异

注:GitHub Container Registry 目前处于公测阶段,可能会更改。 目前,GitHub Container Registry 只支持 Docker 映像格式。 在测试阶段,存储和带宽是免费的。 更多信息请参阅“关于 GitHub Container Registry”。

GitHub Container Registry 取代原有的Packages Docker 注册表,并且做了优化,可支持容器的一些独特需求。

使用容器注册表,您可以:

  • 将容器映像存储在组织和用户帐户中,而不是仓库中。
  • 设置独立于仓库权限和可见性的粒度权限和可见性。
  • 匿名访问公共容器映像。

更多信息请参阅“关于 GitHub Container Registry”。

计费更改

在 GitHub Container Registry 测试期间,新的 container registry 和现有的 GitHub Packages Docker 注册表都是免费的。 有关 GitHub Packages Docker 注册表的更多信息,请参阅“配置 Docker 与 GitHub Packages 一起使用”。

测试后,其他 GitHub Packages 注册表使用的计费和存储率将适用于容器注册表。 更多信息请参阅“关于 GitHub Packages 的计费”。

域更改

container registry 的域是 ghcr.io

注册表Example URL
GitHub Packages Docker 注册表docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME
GitHub Container Registryghcr.io/OWNER/IMAGE_NAME

使用容器注册表进行身份验证

您需要使用基本 URL ghcr.io 向 container registry 验证。 我们建议创建新的访问令牌以使用 container registry。

If you want to authenticate to GitHub Container Registry in a GitHub Actions workflow, then you must use a personal access token (PAT). The GITHUB_TOKEN does not currently have the required permissions. During the GitHub Container Registry beta, the only supported form of authentication is the PAT.

PATs can grant broad access to your account. We recommend selecting only the necessary read, write, or delete package scope when creating a PAT to authenticate to the container registry. Avoid including the repo scope in a PAT used by a GitHub Actions workflow because it gives unnecessary additional access.

If you'd like to use the container registry in actions during the beta, follow our security best practices for PAT use at "Security hardening for GitHub Actions."

  1. 针对要完成的任务,新创具有适当作用域的个人访问令牌 (PAT)。 如果您的组织需要 SSO,则必须为新令牌启用 SSO。

    Note: If you select the write:packages scope, deselect the repo scope when creating the PAT. Adding a PAT with the repo scope as a secret in your repository allows the credential to be accessible to all collaborators in the repository. This gives unnecessary additional access when a PAT with the repo scope is used within an action. For more information on security best practices for actions, see "Security hardening for GitHub Actions."

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

    更多信息请参阅“创建用于命令行的个人访问令牌。”

  2. 保存您的 PAT。 我们建议将 PAT 保存为环境变量。

    $ export CR_PAT=YOUR_TOKEN
  3. Using the CLI for your container type, sign in to the GitHub Container Registry service at ghcr.io.

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

使用 Docker CLI 迁移 Docker 映像

要移动您在 GitHub Packages Docker 注册表上托管的 Docker 映像,您必须将映像重新发布到 container registry。 我们建议在本地计算机上使用命令行重新发布现有的 Docker 映像。

  1. 使用作用域至少为 read:packages 的临时 PAT 登录到 Docker 注册表。 此 PAT 将仅用于登录到 Docker 注册表以下拉映像,然后可以删除。

    $ echo $READ_PACKAGES_TOKEN | docker login docker.pkg.github.com -u USERNAME --password-stdin
  2. 下拉要迁移的映像,将 OWNER 替换为拥有仓库的用户或组织帐户的名称,将 REPOSITORY 替换为包含项目的仓库,将 IMAGE_NAME 替换为包或映像的名称,将 VERSION 替换为要安装的映像的标记。 例如,docker ull docker.pkg.github.com/octo-org/octoshift/octoshift:latest 拉取 octo-org 组织中 octoshift/octoshift 映像的最新标记。

    $ docker pull docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
  3. 使用新域和新映像名称重新标记映像。 更多信息请参阅 Docker 文档中的“Docker 标记”。 使用在上一步中用于 SOURCE URL 同一个URL。 将 TARGET_OWNER 替换为要将容器映像迁移到其中的用户或组织,将 TARGET_IMAGE_NAME 替换为新 container registry 映像名称。

    $ docker tag docker.pkg.github.com/SOURCE_OWNER/SOURCE_REPOSITORY/SOURCE_IMAGE_NAME:VERSION ghcr.io/TARGET_OWNER/TARGET_IMAGE_NAME:VERSION
  4. 登录到新的

container registry. 我们建议创建限于 read:packageswrite:packages 范围的新 PAT,因为您不再需要 repo 范围,并且您之前的 PAT 不能具有 write:packages 范围。

$ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
  1. 将重新标记的映像推送到 container registry。
    $ docker push ghcr.io/OWNER/IMAGE_NAME:VERSION

更新 GitHub Actions 工作流程

如果您有 GitHub Actions 工作流程使用来自 GitHub Packages Docker 注册表的 Docker 映像,则可能需要将工作流程更新到 container registry,以允许匿名访问公共容器映像、更细致的访问权限以及更好的容器存储和带宽兼容性。

  1. 将 Docker 映像迁移到 ghcr.io 上的新 container registry。 例如,请参阅“使用 Docker CLI 迁移 Docker 映像”。

  2. 在 GitHub Actions 工作流程文件中,将包 url 从 https://docker.pkg.github.com 更新到 ghcr.io

  3. 将新的 container registry 身份验证个人访问令牌 (PAT) 添加为 GitHub ACtions 密码。 GitHub Container Registry 不支持对 PAT 使用 GITHUB_TOKEN,因此您必须使用不同的自定义变量,例如 CR_PAT。 更多信息请参阅“创建和存储加密密码”。

  4. 在 GitHub Actions 工作流程文件中更新身份验证 PAT,将 Docker 注册表 PAT (${{ secrets.GITHUB_TOKEN }}) 替换为 container registry PAT 的新变量,例如 ${{ secrets.CR_PAT }}

更新的工作流程示例

如果工作流程的一部分访问由 Docker 注册表托管的 Docker 映像,如:

echo ${{ secrets.GITHUB_TOKEN }} | docker login https://docker.pkg.github.com -u $GITHUB_ACTOR --password-stdin
docker pull docker.pkg.github.com/github/octoshift/octoshift:latest
docker build . --tag docker.pkg.github.com/github/octoshift/octoshift:$GITHUB_SHA --cache-from docker.pkg.github.com/github/octoshift/octoshift:latest
docker push docker.pkg.github.com/github/octoshift/octoshift:$GITHUB_SHA

然后,您需要使用新的 URL 和 PAT container registry 更新工作流程,如:

# new login with new container registry url and PAT
echo ${{ secrets.CR_PAT }} | docker login ghcr.io -u $GITHUB_ACTOR --password-stdin
# new container registry urls added
docker pull ghcr.io/github/octoshift:latest
docker build . --tag ghcr.io/github/octoshift:$GITHUB_SHA --cache-from ghcr.io/github/octoshift:latest
docker push ghcr.io/github/octoshift:$GITHUB_SHA

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。