使用自定义映像

自定义映像

您可以创建自定义映像以定义您的 GitHub 托管的大型运行器所使用的确切环境。自定义映像允许预安装工具、依赖项和配置，以加快工作流的速度，并提高作业之间的一致性。

当您的运行程序使用自定义映像时，它相当于一个"预热"环境，使工作流能够更快完成，因为在创建映像时只需下载一次包和二进制文件，而不是每次运行工作流时都下载。有关自定义映像的详细信息，请参阅运行程序映像。

使用自定义映像的过程涉及三个主要步骤： 1. 设置镜像生成运行程序：创建大型运行器以构建和存储自定义镜像。 1. 生成自定义映像：使用映像生成运行程序运行工作流生成自定义映像。 1. 安装自定义映像：创建使用自定义映像的运行程序。

先决条件

在创建自定义映像之前，请确保满足以下要求。

策略：必须为组织或企业启用自定义映像。企业所有者可以在“作”策略设置中管理对自定义映像的访问权限并设置保留策略。有关详细信息，请参阅“在企业中强制实施GitHub Actions策略”。
权限：若要创建和管理自定义映像，你必须是组织或企业所有者，或者具有CI/CD Admin或拥有以下细化权限的角色。
- 查看组织托管运行器自定义镜像
- 管理组织托管运行器自定义映像
- 管理组织运行器和运行器组
有关详细信息，请参阅“自定义组织角色的权限”。

设置图像生成运行器

若要创建自定义映像，必须先设置映像生成运行程序。创建运行器时，您选择的运行器平台必须与要构建的镜像的平台匹配。运行程序的平台可以是 Linux x64、Linux ARM64 或 Windows x64。

创建大型运行器：
- 对于组织，请参阅向组织添加更大的运行器。
- 对于企业，请参阅向企业添加更大的运行器。
配置运行程序时，为映像生成运行程序选择以下配置：
- 平台：选择与计划创建的映像平台匹配的受支持平台（Linux x64、Linux ARM64 或 Windows x64）。
- 映像：选择要构建的映像，然后启用复选框 “启用此运行程序”以生成自定义映像。
  - 可以从拥有的 GitHub映像开始，也可以选择从干净 OS 开始的基本映像。
  - 对于 ARM64 平台，您还可以选择由 ARM 维护的预装工具的镜像。
- 运行器组：选择您的运行器所属的组。创建自定义映像后，只有此运行器组中的运行器才能创建该映像的新版本。

生成自定义映像

创建映像生成运行程序后，运行包含用于生成自定义映像的 snapshot 关键字的工作流。

若要配置用于生成图像的工作流，请执行以下作：

将 runs-on 值设置为创建的映像生成运行程序的名称。
将关键字snapshot添加到作业中，并使用如下所示的字符串语法或映射语法。
- 包含 snapshot 关键字的每个作业都会创建单独的映像。若要仅生成一个映像或映像版本，请在单个作业中包含所有工作流步骤。
- 包含 snapshot 关键字的作业的每个成功运行都会创建该映像的新版本。

注意

          GitHub 建议将映像生成配置为每周的计划性工作流。 此方法可确保依赖项保持最新并具有最新的安全补丁。 有关详细信息，请参阅“[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#schedule)”。

完成工作流后，映像可能需要一些时间才能完全生成并可供使用。预配时间因运行器大小和配置而异，较大的运行器可能需要数小时。

仅当作业成功完成时，才会生成映像。这样可以防止在工作流失败或以不完整状态结束时创建新的映像版本。

生成映像后，它可用于工作流。有关管理自定义映像的详细信息，请参阅管理自定义映像。

字符串语法

可以使用字符串语法 snapshot 来定义图像名称。此方法创建新的映像或向具有相同名称的现有映像添加新版本。不能使用此语法指定版本号。

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: my-custom-image
    steps:
      # Add any steps to download and setup any dependencies here

映射语法

可以使用映射语法与snapshot一起定义image-name和可选的version。当你指定主版本时，如果该主版本已存在，次版本会自动递增。不支持补丁版本。

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

如果指定的主版本已存在，新映像将使用下一个次要版本（例如，1.0 变为 1.1）。
如果主版本不存在， GitHub 请创建新的主版本（例如 2.0）。

不支持补丁版本。

自定义映像的计费和存储

使用自定义映像的作业按与使用该映像的作业相同的每分钟费率大型运行器计费。自定义映像的存储通过 GitHub Actions 存储单独计费。

如果经常重新生成映像并保留旧版本，存储使用量可能会很快增长，因为包含 snapshot 关键字的每个成功工作流作业都会创建新的映像版本。有关详细信息，请参阅 GitHub Actions计费和在企业中强制实施GitHub Actions策略。

管理自定义映像

可以查看有关每个映像的详细信息、删除未使用的映像或特定版本，以及跟踪一段时间内的映像版本。

在 GitHub 上，导航到组织的主页面。
在组织名称下，单击 “Settings”****。如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。
在左侧边栏中，单击操作，然后单击 “自定义图像”。
在“自定义映像”页上，可以查看已在组织或企业中创建的所有自定义映像。
若要查看有关特定图像的详细信息，请单击映像名称。

安装自定义映像

自定义映像准备就绪后，您可以将其安装到新的 GitHub 托管的大型运行器上。

按照以下步骤创建大型运行器：
- 对于组织，请参阅向组织添加更大的运行器。
- 对于企业，请参阅向企业添加更大的运行器。
配置运行器时：
- 平台：选择用于生成映像的同一平台（Linux x64、Linux ARM64 或 Windows x64）。
- 图像：选择 “自定义 ”选项卡，然后从列表中选择自定义映像。
  - 如果看不到你的映像，请确保你已选择正确的平台，并且正在与生成映像的同一级别（组织或企业）创建运行器。
- 映像版本：选择 “最新 ”以自动使用最新版本，或选择特定的版本号将运行程序固定到该版本。
  - 如果选择 “最新”，则运行程序会在新版本的映像可用时自动更新。如果将运行器固定到特定版本，以后需要手动编辑运行器才能升级。
- 大小：选择存储容量等于或大于你的映像大小的运行器大小。例如，如果映像是在 8 核运行器上生成的，请选择一个 8 核或更大的运行器来运行该映像。
- 运行程序组：将运行程序分配到与需要使用此映像的存储库共享的运行程序组。

在您的 GitHub Actions 工作流任务中，将 runs-on 键设置为运行程序的名称。

jobs: 
  build:
    runs-on: my-custom-runner
    steps:
    # Add any steps for your workflow here

运行工作流以验证它是否已成功完成。作业日志将在“设置作业”部分中显示映像名称和版本。

自定义映像的安全最佳做法

若要防止对映像进行未经授权的更改，请遵循以下最佳做法。

使用专用运行器组生成镜像。 用于生成生产映像的运行器必须保持在专用运行器组中。请勿在生产与开发或测试存储库之间共享运行程序组，因为有权访问开发或测试存储库的任何人都可以将恶意代码注入生产映像。
不允许公共存储库访问映像生成运行程序。 将能够使用图像生成运行器的存储库限制为仅真正需要的存储库，并定期审查访问权限。
将最低权限应用于存储库。 避免为有权访问图像生成运行器的存储库授予组织范围的 write 访问权限。由于可以从任何分支生成映像，因此具有写入访问权限的任何人都可以创建具有任意代码的分支并触发映像生成。

谁可以使用此功能？

在本文中