迁移到 Docker 映像的 GitHub Container Registry

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

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。

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

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

如果要向 GitHub Actions 工作流程中的 GitHub Container Registry 验证，则您必须使用个人访问令牌 (PAT)。 GITHUB_TOKEN 目前没有所需的权限。 在 GitHub Container Registry 测试阶段，唯一支持的身份验证形式是 PAT 。

PAT 可以授予对您的帐户的广泛访问权限。 在创建 PAT 以向 container registry 验证时，我们建议只选择必要的读取、写入或删除 package 作用域。 避免在 GitHub Actions 工作流程使用的 PAT 中包括 repo 作用域，因为它会授予不必要的额外访问权限。

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

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

   注：如果选择 write:packages 作用域，请在创建 PAT 时取消选择 repo 作用域。 将具有 repo 作用域的 PAT 添加为仓库中的机秘，可让仓库中的所有协作者访问该机密。 这会在操作中使用作用域为 repo 的 PAT 时授予不必要的额外访问权限。 有关操作安全最佳实践的更多信息，请参阅“GitHub Actions 的安全强化”。

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

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

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

   $ export CR_PAT=YOUR_TOKEN

3. 使用您的容器类型的 CLI 登录到 ghcr.io 上的 GitHub 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:packages 和 write: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. 将新的 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