允许您的 Codespace 访问私有注册表

关于私有注册表和 GitHub Codespaces

注册表是用于存储、管理和获取容器镜像或其他软件包的安全空间。注册表的示例很多，例如

GitHub 的容器注册表、Azure 容器注册表和 DockerHub（用于容器镜像）
npm 注册表（用于 Node.js 软件包）。

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

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

使用细粒度权限访问存储在注册表中的软件包

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

访问发布到与 codespace 相同仓库的软件包

如果您在与 codespace 启动所在的相同仓库中发布包，您将能够在 codespace 创建时自动获取该包。您无需提供任何其他凭据，除非在发布包时未选中 **从仓库继承访问权限** 选项。

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

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

此行为由 **从仓库继承访问权限** 选项控制。**从仓库继承访问权限** 在通过 GitHub Actions 发布时默认选中，但在使用个人访问令牌直接发布到注册表时不会选中。

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

访问发布到 codespace 将要启动的组织的包

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

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

从组织中的部分仓库访问私有包

如果您希望允许组织中的一部分仓库访问某个包，或者允许从公共仓库中启动的 Codespace 访问内部或私有包，您可以手动将仓库添加到包的访问设置中。有关更多信息，请参阅“配置包的访问控制和可见性”。

从 Codespace 发布包

从 Codespace 无缝访问注册表仅限于拉取包。如果您想从 Codespace 内部发布包，则必须使用具有 write:packages 范围的个人访问令牌（经典）。

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

访问存储在其他注册表中的镜像

您可以定义秘密，以允许 GitHub Codespaces 访问除 GitHub 容器注册表以外的容器镜像注册表。如果您要从不支持无缝访问的注册表访问容器镜像，GitHub Codespaces 会检查三个秘密的存在，这些秘密定义了注册表的服务器名称、用户名和个人访问令牌。如果找到这些秘密，GitHub Codespaces 将在您的 Codespace 中提供注册表。

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

您可以将密钥存储在用户、仓库或组织级别，以便在不同的 Codespaces 之间安全地共享密钥。当您为私有镜像仓库创建一组密钥时，需要将名称中的“<*>”替换为一致的标识符。有关更多信息，请参阅“管理您的帐户特定密钥以用于 GitHub Codespaces”和“管理您的仓库或组织的开发环境密钥”。

如果您在用户或组织级别设置密钥，请确保通过从下拉列表中选择访问策略，将这些密钥分配给您将要创建 Codespaces 的仓库。

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

GitHub Codespaces 使用 Docker，因此要在运行时将私有 Docker 镜像拉取到您的 Codespace 中，您需要能够使用 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) 不同。

Screenshot of the "Codespaces secrets" settings for a repository. Three secrets for ACR Container Registry are set.

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

访问 AWS Elastic Container Registry

要访问 AWS Elastic Container Registry (ECR)，您可以提供 AWS 访问密钥 ID 和密钥，GitHub 可以为您检索访问令牌并代表您登录。

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

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

或者，如果您不想让 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 Elastic Container Registry - <aws_account_id>.dkr.ecr.<region>.amazonaws.com
Google Cloud Container Registry - gcr.io（美国）、eu.gcr.io（欧盟）、asia.gcr.io（亚洲）

调试私有镜像注册表访问

如果您在从私有镜像仓库拉取镜像时遇到问题，请确保您可以使用上面定义的密钥值运行 docker login -u <user> -p <password> <server>。如果登录失败，请确保登录凭据有效，并且您在服务器上具有获取容器镜像的适当权限。如果登录成功，请确保这些值已正确复制到正确的 GitHub Codespaces 密钥中，无论是用户、仓库还是组织级别，然后重试。

允许您的 codespace 访问私有注册表

本文档