允许 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 发布时，默认情况下会选中**从仓库继承访问权限**，但使用个人访问令牌直接发布到注册表时不会选中。

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

访问发布到组织的代码空间将启动的包

如果希望所有代码空间都能访问某个包，建议您发布具有内部可见性的包。这将自动使包对组织内的所有代码空间可见，除非启动代码空间的仓库是公开的。

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

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

如果要允许组织中的部分仓库访问包，或允许从在公共仓库中启动的代码空间访问内部或私有包，可以手动将仓库添加到包的访问设置中。有关更多信息，请参阅“配置包的访问控制和可见性”。

从代码空间发布包

代码空间与注册表之间的无缝访问仅限于拉取包。如果要从代码空间内部发布包，必须使用具有write:packages作用域的个人访问令牌（经典版）。

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

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

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

<*>_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."

GitHub Codespaces 使用 Docker，因此要在运行时将私有 Docker 镜像拉取到您的代码空间中，您需要能够使用 Docker-in-Docker。为实现此目的，用于登录 Docker 的密钥会自动添加到代码空间内的~/.docker/config.json文件中。这发生在onCreateCommand生命周期挂钩之后，但在postCreateCommand、postStartCommand和postAttachCommand之前。因此，postCreateCommand将能够使用 Docker-in-Docker 将 Docker 镜像拉取到代码空间中，但onCreateCommand不能。因此，在预构建创建期间不可用 Docker-in-Docker。

代码空间运行后，您将能够在代码空间中打开终端并运行命令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.

添加密钥后，您可能需要停止然后启动您所在的代码空间，以便将新的环境变量传递到容器中。有关更多信息，请参阅“在 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 注册表，否则我们建议使用ECR_CONTAINER_REGISTRY_*。

有关更多信息，请参阅 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 容器注册表 - gcr.io（美国）、eu.gcr.io（欧盟）、asia.gcr.io（亚洲）

调试私有镜像注册表访问

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

本文内容