限制 codespace 的基础映像

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

谁可以使用此功能？

To manage image constraints for an organization's codespaces, you must be an owner of the organization.

使用 GitHub Team 和 GitHub Enterprise 计划的组织可以为成员和协作者对 GitHub Codespaces 的使用付费。 然后，这些组织可以访问设置和策略来管理由组织支付的 codespace。 有关详细信息，请参阅“选择谁拥有组织中的 codespace 并为其付费”和“GitHub 的计划”。

本文内容

概述

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

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

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

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

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

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

作为组织所有者，你可以添加一个策略来限制哪些开发容器映像可用于组织内创建的 codespace。

如果你尝试用来创建 Codespace 的 devcontainer.json 指定了策略不允许的映像，则会在 GitHub 中显示以下消息：

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

使用 CLI 时，错误消息将为：

创建 Codespace 时出错：HTTP 400：根据组织管理员设置的组织策略，基础映像“IMAGE-REFERENCE”不被允许。

如果在 Dockerfile 中指定了 Codespace 的映像，但该映像不符合策略，则将使用默认的恢复容器在恢复模式下创建 Codespace，而不是使用指定的映像。 说明此后果的消息将包含在创建日志的末尾。 有关创建日志的详细信息，请参阅“GitHub Codespaces 日志”。

Note

  • 不应将开发容器基础映像与主机映像混淆。 主机映像用于生成运行开发容器的虚拟机。 有关详细信息，请参阅“选择稳定版本或 beta 版本主机映像”。
  • 基础映像策略将在创建 Codespace 以及执行完整容器重新生成时应用。 有关详细信息，请参阅“了解 codespace 生命周期”。
  • 基本映像策略不适用于默认映像，也不适用于在开发容器配置中引入错误导致无法重新生成容器的情况下用于恢复 codespace 的映像。

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

创建策略时，您可以选择是将其应用于组织中的所有存储库，还是仅应用于指定的存储库。 如果设置了组织范围的策略，则为各个存储库设置的任何策略都必须在组织级别设置的限制范围内。 添加策略会增加映像的限制，而不是减少。

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

Note

Codespace 策略仅适用于组织支付的 codespace。 如果某人为组织中的存储库创建 codespace，并自行付费，则 codespace 不受这些策略的约束。 有关详细信息，请参阅“选择谁拥有组织中的 codespace 并为其付费”。

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

  1. 在 GitHub 的右上角，选择个人资料照片，然后单击 “你的组织”。

  2. 在组织旁边，单击“设置”。

  3. 在边栏的“代码、规划和自动化”部分中，选择“ Codespaces”，然后单击“策略” 。

  4. 在“codespace 策略”页上，单击“创建策略”。****

  5. 输入新策略的名称。

  6. 单击“添加约束”并选择“基础映像” 。

  7. 单击 编辑约束。

  8. 在“允许的值”字段中，输入要允许的 Docker 映像的映像引用。

    在“允许的值”字段中输入的映像引用“mcr.microsoft.com/devcontainers/java”的屏幕截图。

    可以使用 * 通配符作为映像引用的最后一个字符，以匹配引用的开始部分与该通配符左侧字符相同的所有映像。 例如，mcr.microsoft.com/devcontainers/*。

  9. 单击“”添加值。

  10. 如果需要，请重复前两个步骤以添加更多映像引用。

    添加多个映像引用时，如果存储库的开发容器配置中指定的映像引用与应用于存储库策略中的任何引用不一致，则无法为该存储库创建 Codespace。

  11. 单击对话框外部将其关闭。

  12. 默认情况下，策略设置为应用于所有存储库，如果你希望它仅应用于组织中的某些存储库，请单击“所有存储库”，然后在下拉菜单中单击“所选存储库”。

    存储库选择下拉列表的屏幕截图，其中显示了“所有存储库”和“所选存储库”选项。

    Note

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

    选中“所选存储库”后：

    1. 单击 。

      标有“所选存储库”的按钮左侧的“设置”图标的屏幕截图（齿轮符号)。

    2. 选择要应用此策略的存储库。

    3. 在存储库列表的底部，单击“选择存储库”。

      存储库列表的屏幕截图，每个存储库都有一个复选框。 已选择三个存储库。

  13. 如果要向策略添加另一个约束，请单击“添加约束”并选择另一个约束。 有关其他约束的信息，请参阅：

  14. 向策略添加完约束后，单击“保存”。

当有人尝试创建可向组织收费的新 codespace 时，将应用该策略。 基本映像约束不会影响现有 codespace（无论是活动的还是停止的）。

编辑策略

可以编辑现有策略。 例如，你可能想要在策略中添加或移除约束。

  1. 显示“Codespace policies（代码空间策略）”页。 有关详细信息，请参阅“添加策略以定义允许的映像”。
  2. 单击要编辑的策略的名称。
  3. 在“基础映像”约束旁，单击“”。
  4. 添加或移除映像引用。
  5. 单击“ 保存”。

删除策略

  1. 显示“Codespace policies（代码空间策略）”页。 有关详细信息，请参阅“添加策略以定义允许的映像”。

  2. 在要删除的策略的右侧，单击“”。

    策略的屏幕截图，其中“删除”按钮（垃圾桶图标）以深橙色边框突出显示。