限制 Codespaces 的基础映像

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

谁可以使用此功能？

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

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

本文内容

概述

当你创建一个 Codespace 时，会自动在远程虚拟机上创建一个开发容器。此开发容器是从 Docker 镜像创建的。镜像实际上是 Docker 容器的模板，它决定了 Codespace 提供的结果环境的许多方面。有关详细信息，请参阅“GitHub Codespaces 概述”。

你可以通过在存储库的开发容器配置中指定要用于 Codespace 的镜像来选择要使用的镜像。例如，可以通过在 `devcontainer.json` 文件中使用 `image` 属性来执行此操作。

JSON

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

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

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

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

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

作为组织所有者，你可以添加策略来限制可在组织内创建的 Codespace 中使用的开发容器镜像。

如果你尝试使用指定了策略不允许的镜像的 `devcontainer.json` 创建 Codespace，则 GitHub.com 中将显示以下消息。

无法创建 Codespace，因为开发容器配置中指定的镜像不允许。你可能需要选择其他分支、修改容器配置或调整组织的策略设置。

使用 CLI 时，错误消息为

错误：创建 Codespace：HTTP 400：基于组织管理员设置的组织策略，不允许基础镜像“IMAGE-REFERENCE”。

如果 Codespace 的镜像在 Dockerfile 中指定，并且与策略不匹配，则会使用默认恢复容器而不是指定的镜像在恢复模式下创建 Codespace。创建日志的末尾包含一条此类消息。有关创建日志的详细信息，请参阅“GitHub Codespaces 日志”。

注释:

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

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

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

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

注意：代码空间策略仅适用于组织付费的代码空间。如果有人自费为组织中的存储库创建了代码空间，那么该代码空间将不受这些策略的约束。有关详细信息，请参阅“选择组织中代码空间的所有者和付费方”。

添加策略来定义允许的映像

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

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

当您添加多个映像引用时，如果存储库的开发容器配置中指定的映像引用与适用于该存储库的策略中的任何引用不匹配，您将无法为该存储库创建 Codespaces。
单击对话框外部以关闭它。
默认情况下，该策略设置为应用于所有存储库，如果您希望它仅应用于组织中的一些存储库，请单击所有存储库，然后在下拉菜单中单击选定的存储库。

注意：如果您正在向已包含“每个用户最大 Codespaces 数”约束的现有策略添加约束，您将无法将该策略应用于选定的存储库。这是因为“每个用户最大 Codespaces 数”约束始终应用于组织中的所有存储库。

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

当任何人尝试创建对您的组织计费的新 Codespace 时，将应用该策略。基础映像约束不会影响现有的 Codespace，无论其处于活动状态还是已停止状态。

编辑策略

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

显示“Codespace 策略”页面。有关详细信息，请参阅“添加策略以定义允许的映像”。
单击您要编辑的策略的名称。
在“基础映像”约束旁边，单击 .
添加或移除映像引用。
单击保存。

删除策略

显示“Codespace 策略”页面。有关详细信息，请参阅“添加策略以定义允许的映像”。
单击到您要删除的策略的右侧。