限制 Codespaces 的基础镜像

您可以指定哪些基础镜像可用于创建在您的组织内创建的新 Codespaces 的开发容器。

谁可以使用此功能？

要管理组织的 Codespaces 的镜像约束，您必须是该组织的所有者。

GitHub 团队和 GitHub Enterprise 计划上的组织可以支付其成员和协作者使用 GitHub Codespaces 的费用。这些组织随后可以访问设置和策略来管理组织支付的 Codespaces。有关更多信息，请参阅“选择谁拥有和支付组织中的 Codespaces”和“GitHub 的计划”。

本文内容

概述

创建代码空间时，会在远程虚拟机上自动创建一个开发容器。此开发容器由 Docker 镜像创建。镜像实际上是 Docker 容器的模板，它决定了代码空间提供的最终环境的许多方面。有关更多信息，请参阅“GitHub 代码空间概述”。

您可以通过在存储库的开发容器配置中指定它来选择要用于代码空间的镜像。例如，您可以通过在 devcontainer.json 文件中使用 image 属性来实现。

JSON

"image": "mcr.microsoft.com/devcontainers/javascript-node:18",

"image": "mcr.microsoft.com/devcontainers/javascript-node:18",

有关更多信息，请参阅开发容器网站上的开发容器规范。

或者，您可以在 Dockerfile 中指定基础镜像。有关更多信息，请参阅“开发容器简介”。

如果您未在存储库的开发容器配置中指定镜像，则将使用默认的开发容器镜像。默认镜像包含许多流行语言和常用工具的运行时版本。有关更多信息，请参阅“开发容器简介”。

作为组织所有者，您可以添加策略以限制可以在组织内创建的代码空间中使用的开发容器镜像。

如果您尝试使用指定了策略不允许的镜像的 devcontainer.json 创建代码空间，则 GitHub 中会显示以下消息

无法创建代码空间，因为开发容器配置中指定的镜像不允许使用。您可能需要选择不同的分支、修改容器配置或调整组织的策略设置。

使用 CLI 时，错误消息为

error creating codespace: HTTP 400: 基于组织管理员设置的组织策略，基础镜像“IMAGE-REFERENCE”不允许。

如果代码空间的镜像在 Dockerfile 中指定，并且与策略不匹配，则会以恢复模式创建代码空间，使用默认恢复容器而不是指定的镜像。创建日志的末尾包含一条说明此情况的消息。有关创建日志的更多信息，请参阅“GitHub 代码空间日志”。

注意

开发容器基础镜像不应与主机镜像混淆。主机镜像是用于构建运行开发容器的虚拟机的镜像。有关更多信息，请参阅“选择稳定版或测试版主机镜像”。
创建代码空间时以及执行完整容器重建时，都会应用基础镜像策略。有关更多信息，请参阅“了解代码空间生命周期”。
基础镜像策略不适用于默认镜像，也不适用于在开发容器配置中引入错误导致无法重建容器时用于恢复代码空间的镜像。

设置组织范围和存储库特定的策略

创建策略时，您可以选择将其应用于组织中的所有存储库，还是仅应用于指定的存储库。如果设置了组织范围的策略，则为各个存储库设置的任何策略都必须符合组织级别设置的限制。添加策略会使镜像的选择更加严格，而不是更宽松。

例如，您可以创建一个组织范围的策略，将基础镜像限制为十个指定镜像中的任何一个。然后，您可以为存储库 A 设置一个策略，将镜像限制为组织级别指定的两个镜像的子集。为存储库 A 指定其他镜像将无效，因为这些镜像未在组织级别策略中指定。如果添加组织范围的策略，则应将其设置为组织中任何存储库都可用的最大镜像选择。然后，您可以添加存储库特定的策略来进一步限制选择。

注意

代码空间策略仅适用于组织付费的代码空间。如果有人自行承担费用为组织中的存储库创建代码空间，则该代码空间不受这些策略约束。有关更多信息，请参阅“选择组织中谁拥有和支付代码空间”。

添加策略以定义允许的镜像

在 GitHub 的右上角，选择您的个人资料照片，然后单击 您的组织.
在组织旁边，单击**设置**。
在侧边栏的“代码、计划和自动化”部分，选择** 代码空间**，然后单击**策略**。
在“代码空间策略”页面上，单击**创建策略**。
输入新策略的名称。
单击**添加约束**并选择**基础镜像**。
单击以编辑约束。
在“允许的值”字段中，输入要允许的 Docker 镜像的镜像引用。

您可以使用 * 通配符作为镜像引用的最后一个字符，以匹配以通配符左侧相同的引用开头的所有镜像。例如，mcr.microsoft.com/devcontainers/*。
单击以添加值。
如果需要，重复前两个步骤以添加更多镜像引用。

添加多个镜像引用时，如果存储库的开发容器配置中指定的镜像引用与应用于该存储库的策略中的任何引用都不匹配，则您将无法为该存储库创建代码空间。
单击对话框外部以将其关闭。
默认情况下，策略设置为应用于所有存储库，如果只想将其应用于组织中的一些存储库，请单击**所有存储库**，然后在下拉菜单中单击**选定的存储库**。

注意

如果要向已包含“每个用户最大代码空间数”约束的现有策略添加约束，则无法将策略应用于选定的存储库。这是因为“每个用户最大代码空间数”约束始终应用于组织中的所有存储库。

选择**选定的存储库**后
1. 单击.
2. 选择要应用此策略的存储库。
3. 在存储库列表底部，单击**选择存储库**。
如果要向策略添加其他约束，请单击**添加约束**并选择其他约束。有关其他约束的信息，请参阅
完成向策略添加约束后，单击**保存**。

当任何人尝试创建对组织计费的新代码空间时，将应用该策略。基础镜像约束不影响现有的代码空间，无论是活动的还是已停止的。

编辑策略

您可以编辑现有策略。例如，您可能希望向策略添加或删除约束。

显示“代码空间策略”页面。有关更多信息，请参阅“添加策略以定义允许的镜像”。
单击要编辑的策略的名称。
在“基础镜像”约束旁边，单击.
添加或删除镜像引用。
单击**保存**。

删除策略

显示“代码空间策略”页面。有关更多信息，请参阅“添加策略以定义允许的镜像”。
单击在要删除的策略右侧。