允许 codespace 访问专用注册表

关于专用注册表和 GitHub Codespaces

注册表是用于存储、管理和提取容器映像的安全空间。注册表有许多示例，例如：

GitHub 的 Container registry、Azure 容器注册表和用于容器映像的 DockerHub
用于 Node.js 包的 npm registry。

某些 GitHub Packages 注册表（包括 Container registry）可以配置为允许在创建 codespace 期间无缝地将容器映像拉取到 GitHub Codespaces 中，而无需提供任何身份验证凭据。

若要访问其他容器映像注册表，可在 GitHub 中创建机密以存储访问详细信息，这将允许 GitHub Codespaces 访问存储在该注册表中的映像。

使用精细权限访问存储在注册表中的包

支持精细权限的 GitHub Packages 注册表（包括 Container registry）为 GitHub Codespaces 使用包提供了最简单的方法。有关支持精细权限和无缝 GitHub Codespaces 访问的 GitHub Packages 注册表的列表，请参阅“关于 GitHub Packages 的权限”。

访问发布到与 codespace 相同的存储库的映像

如果在启动 codespace 的同一存储库中发布包，你将能够在创建 codespace 时自动提取该包。无需提供任何其他凭据，除非在发布包时未选中“从存储库继承访问权限”选项。

从发布包的存储库继承访问权限

默认情况下，包继承发布它的存储库的访问设置。例如，如果存储库是公共的，则包也是公共的。如果存储库是私有的，则包也是私有的，但可以从存储库访问。

此行为由“从存储库继承访问权限”选项控制。通过 GitHub Actions 发布时，默认情况下会选择“从存储库继承访问权限”，但在使用 personal access token 直接发布到注册表时，不会选择该选项。

如果在发布包时未选择“从存储库继承访问权限”选项，则可以手动将存储库添加到已发布包的访问控制中。有关详细信息，请参阅“配置包的访问控制和可见性”。

访问发布到组织、codespace 将在其中启动的包

如果希望组织中的所有 codespace 都可以访问包，建议发布具有内部可见性的包。这将自动使包对组织内的所有 codespace 可见，除非从中启动 codespace 的存储库是公开的。

如果 codespace 是从引用内部或专用包的公共存储库启动的，则必须手动允许公共存储库访问内部包。这可以防止内部包意外公开泄露。有关详细信息，请参阅“配置包的访问控制和可见性”。

从组织中存储库的子集访问专用包

如果要允许组织的存储库子集访问包，或者允许从在公共存储库中启动的 codespace 访问内部或专用包，则可以手动将存储库添加到包的访问设置。有关详细信息，请参阅“配置包的访问控制和可见性”。

从 codespace 发布包

从 codespace 到注册表的无缝访问仅限于拉取包。如果要从 codespace 内部发布包，则必须结合使用 personal access token (classic) 与 write:packages 作用域。

我们建议通过 GitHub Actions 发布包。有关详细信息，请参阅“发布 Docker 映像”和“发布 Node.js 包”。

可以定义机密以允许 GitHub Codespaces 访问除 GitHub 的 Container registry 以外的容器映像注册表。如果要从不支持无缝访问的注册表访问容器映像，GitHub Codespaces 将检查是否存在三个机密，这些机密定义了容器注册表的服务器名称、用户名和 personal access token。如果找到这些密钥，GitHub Codespaces 将在 codespace 中提供注册表。

<*>_CONTAINER_REGISTRY_SERVER
<*>_CONTAINER_REGISTRY_USER
<*>_CONTAINER_REGISTRY_PASSWORD

您可以在用户、仓库或组织级别存储密钥，从而在不同的代码空间之间安全地共享它们。当您为私有映像注册表创建一组密钥时，您需要用一致的标识符替换名称中的 “<*>”。有关详细信息，请参阅“管理 GitHub Codespaces 特定于帐户的机密”和“管理存储库或组织的开发环境机密”。

如果您在用户或组织级别设置机密，请确保将这些机密分配到仓库，您将从下拉列表中选择访问策略来创建代码空间。

Screenshot of the "Repository access" dropdown menu with the options "All repositories," "Private repositories," and "Selected repositories."

将 Docker 映像拉取到 Codespace

GitHub Codespaces 使用 Docker，因此要在运行时在 Codespace 内拉取专用 Docker 映像，则需要具有使用 Docker-in-Docker 的权限。为实现此目标，系统会自动将登录到 Docker 所需的机密加到 Codespace 中的 ~/.docker/config.json 文件。这发生在 onCreateCommand 生命周期挂钩之后、postCreateCommand、postStartCommand 和 postAttachCommand 之前。因此，postCreateCommand 将能够使用 Docker-in-Docker 将 Docker 映像拉入 Codespace，但 onCreateCommand 不能实现此目标。因此，在预生成创建期间，Docker-in-Docker 将不可用。

Codespace 开始运行后，你将能够在 codespace 中打开终端并运行命令 docker pull PRIVATE-IMAGE-URL。

示例机密

如果您在 Azure 中拥有私有映像注册表，则可以创建以下机密：

ACR_CONTAINER_REGISTRY_SERVER = mycompany.azurecr.io
ACR_CONTAINER_REGISTRY_USER = acr-user-here
ACR_CONTAINER_REGISTRY_PASSWORD = <PERSONAL_ACCESS_TOKEN>

有关通用映像注册表的信息，请参阅“通用映像注册表服务器”。请注意，访问 AWS Elastic Container Registry (ECR) 是不同的。

存储库的“Codespaces 机密”设置的屏幕截图。设置了 ACR 容器注册表的三个机密。

添加机密后，您可能需要停止并启动您所在的代码空间，以便将新的环境变量传递到容器。有关详细信息，请参阅“在 GitHub Codespaces 中使用 Visual Studio Code 命令面板”。

访问 AWS Elastic Container Registry

要访问 AWS 弹性容器注册表 (ECR)，您可以提供 AWS 访问密钥 ID 和私有密钥，GitHub 可以为您检索访问令牌并代表您登录。

*_CONTAINER_REGISTRY_SERVER = <ECR_URL>
*_CONTAINER_REGISTRY_USER = <AWS_ACCESS_KEY_ID>
*_CONTAINER_REGISTRY_PASSWORD = <AWS_SECRET_KEY>

你还必须确保具有适当的 AWS IAM 权限来执行凭据交换（例如 sts:GetServiceBearerToken）以及 ECR 读取操作（AmazonEC2ContainerRegistryFullAccess 或 ReadOnlyAccess）。

或者，如果你不希望 GitHub 代表你执行凭证交换，则可以提供通过 AWS 的 API 或 CLI 获取的授权令牌。

*_CONTAINER_REGISTRY_SERVER = <ECR_URL>
*_CONTAINER_REGISTRY_USER = AWS
*_CONTAINER_REGISTRY_PASSWORD = <TOKEN>

由于这些令牌的生存期较短，需要定期刷新，因此我们建议提供访问密钥 ID 和机密。

尽管这些机密可以具有任何名称，但只要 *_CONTAINER_REGISTRY_SERVER 是 ECR URL，仍建议使用 ECR_CONTAINER_REGISTRY_*，除非你正在处理多个 ECR 注册表。

有关详细信息，请参阅 AWS ECR 的“专用注册表身份验证文档”。

通用映像注册表服务器

下面列出了一些通用映像注册表服务器：

DockerHub - https://index.docker.io/v1/
GitHub 容器注册表 - ghcr.io
Azure 容器注册表 - <registry name>.azurecr.io
AWS 弹性容器注册表 - <aws_account_id>.dkr.ecr.<region>.amazonaws.com
Google Cloud 容器注册表 - gcr.io (US)、eu.gcr.io (EU)、asia.gcr.io (Asia)

调试私有映像注册表访问

如果在从专用映像注册表中提取映像时遇到问题，请确保能够使用上述机密值运行 docker login -u <user> -p <password> <server>。如果登录失败，请确保登录凭据有效，并且你在服务器上具有提取容器映像的适当权限。如果登录成功，请确保将这些值适当地复制到正确的 GitHub Codespaces 机密中，无论是在用户、仓储库还是组织级别，然后重试。