从 Docker 注册表迁移到容器注册表

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

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


GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按仓库计划的帐户无法访问 Container registry,因为这些帐户是按仓库计费的。 更多信息请参阅“[GitHub 的产品](/articles/github-s-products)”。

Container registry 与 Docker 注册表之间的主要差异

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

通过 Container registry,您可以:

  • 将容器映像存储在组织和用户帐户中,而不是仓库中。
  • 设置独立于仓库权限和可见性的精细权限和可见性。
  • 匿名访问公共容器映像。
Docker 注册表Container registry
托管位置您可以在一个仓库中托管多个 Docker 映像。您可以在一个组织或用户帐户中托管多个容器映像。
权限每个映像都继承托管映像的仓库的权限。

例如,对仓库有读取权限的任何人都可以将包安装为项目中的依赖项,有写入权限的任何人都可以发布新的包版本。
对于每个容器映像,您可以选择其他人具有的访问权限级别。 容器映像访问的权限与组织和仓库权限不同。
可见性您可以在公共仓库中发布包(公共包)以与所有人GitHub共享,或者在私有仓库(私有包)中与协作者或组织共享。您可以设置每个容器映像的可见性。 私有容器映像仅对组织内被授予访问权限的人员或团队可见。 公共容器映像对任何人都可见。

计费更改

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

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

域更改

Container registry 的域是 ghcr.io

注册表示例 URL
GitHub Packages Docker 注册表docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME
Container registryghcr.io/OWNER/IMAGE_NAME

向 Container registry 验证

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

PAT 可以授予对您的帐户的广泛访问权限。 在创建 PAT 以向 Container registry 验证时,您应该只选择必要的 read:packageswrite:packagesdelete:packages 范围。

要在 GitHub Actions 工作流程中向 Container registry 验证,请使用 GITHUB_TOKEN 以获得最佳的安全性和体验。

有关更新使用个人访问令牌向 ghcr.io 验证的工作流程的指南,请参阅“升级访问 ghcr.io 的工作流程”。

如果要在测试期间的操作中使用 Container registry,请遵循我们在“GitHub Actions 的安全强化”中的 PAT 使用安全最佳实践。

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

    注意: 默认情况下, 当您在用户界面中选择 write:packages 范围的个人访问令牌 (PAT) 时,repo 范围也将被选中。 repo 范围提供了不必要和广泛的访问权限,我们建议您尤其避免使用 GitHub Actions 工作流程。 更多信息请参阅“GitHub Actions 的安全性增强”。 作为一种解决方法,您可以在以下 URL 的用户界面中为 PAT 选择 write:packages 范围:https://github.com/settings/tokens/new?scopes=write:packages

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

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

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

    $ export CR_PAT=YOUR_TOKEN
  3. 使用您的容器类型的 CLI 登录到 ghcr.io 上的 Container registry 服务。

    $ 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
  5. 将重新标记的映像推送到 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. 使用 GITHUB_TOKENN 作为身份验证个人访问令牌 (PAT)。 更多信息请参阅“工作流程中的身份验证

  4. 在 GitHub Actions 工作流程文件中,使用身份验证令牌 ${{ secrets.GITHUB_TOKEN }} 作为 Container registry 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 Container registry 更新工作流程,如:

# new login with new container registry url and PAT
echo ${{ secrets.GITHUB_TOKEN }} | 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 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。