GitHub Actions Runner Images 完全指南托管 Runner 虚拟机镜像的构成、发布策略与自定义构建【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images本文以 GitHub 开源仓库 runner-images 的 README.md 为主体结合仓库内 构建文档、Packer 模板与辅助脚本源码系统讲解 GitHub Actions / Azure DevOps 托管运行器Runner虚拟机镜像的完整生态当前提供哪些镜像、标签如何演进、软件预装与版本支持策略如何制定、镜像如何发布与弃用以及开发者如何基于本仓库在 Azure 上构建属于自己的 Runner 镜像。读完本文你将掌握镜像标签选型、版本锁定规避迁移风险的方法并能独立完成从构建 Agent 准备到镜像生成、部署的完整流程。仓库定位托管 Runner 镜像的“源代码”runner-images 仓库保存了用于创建 GitHub Actions 与 Azure DevOps 托管运行器虚拟机镜像的全部源代码。根据 README.md 的 About 章节本仓库生成的镜像同时服务于两类平台GitHub Actions 的 [GitHub-hosted runners] 和 Azure Pipelines 的 Microsoft-hosted agents。这意味着镜像的可用性对两个平台一致但两者在弃用策略上可能有所不同详见 FAQ。值得注意这是一个“生成镜像的仓库”而不是镜像本身。要基于本仓库源码真正构建出一台可用的虚拟机需要按照 docs/create-image-and-azure-resources.md 中的步骤在 Azure 上执行 Packer 构建流程下文最后一节会展开说明。可用镜像一览三大操作系统家族的矩阵README 用一张表格列出了当前仓库定义的全部镜像。截至当前仓库状态可用镜像如下架构、YAML 标签与软件清单的对应关系镜像架构YAML 标签详细软件清单Ubuntu 26.04previewx64ubuntu-26.04Ubuntu2604-Readme.mdUbuntu 26.04 Arm64previewarm64ubuntu-26.04-armUbuntu2604-Arm64-Readme.mdUbuntu 24.04x64ubuntu-latest或ubuntu-24.04Ubuntu2404-Readme.mdUbuntu 24.04 Arm64arm64ubuntu-24.04-armUbuntu2404-Arm64-Readme.mdUbuntu 22.04x64ubuntu-22.04Ubuntu2204-Readme.mdUbuntu 22.04 Arm64arm64ubuntu-22.04-armUbuntu2204-Arm64-Readme.mdUbuntu Slimx64ubuntu-slimubuntu-slim-Readme.mdXcode 27previewarm64xcode-27或xcode-27-xlargexcode-27-arm64-Readme.mdmacOS 26x64macos-latest-large、macos-26-intel、macos-26-largemacos-26-Readme.mdmacOS 26 Arm64arm64macos-latest、macos-26或macos-26-xlargemacos-26-arm64-Readme.mdmacOS 15x64macos-15-large或macos-15-intelmacos-15-Readme.mdmacOS 15 Arm64arm64macos-15或macos-15-xlargemacos-15-arm64-Readme.mdmacOS 14deprecatedx64macos-14-largemacos-14-Readme.mdmacOS 14 Arm64deprecatedarm64macos-14或macos-14-xlargemacos-14-arm64-Readme.mdWindows Server 2025x64windows-latest、windows-2025或windows-2025-vs2026Windows2025-VS2026-Readme.mdWindows Server 2022x64windows-2022Windows2022-Readme.mdWindows 11 Arm64arm64windows-11-armWindows11-Arm64-Readme.mdWindows 11 Arm64带 Visual Studio 2026arm64windows-11-vs2026-armWindows11-VS2026-Arm64-Readme.md仓库中每种镜像都配套了一份独立的 Readme位于images/ubuntu/、images/macos/、images/windows/目录详细列出该镜像中预装的每一项软件及其版本——这既是使用者查询环境的权威依据也是撰写本文时唯一可以确认“包含哪些软件”的事实来源。标签命名方案Label scheme理解镜像标签是使用托管 Runner 的第一步README 明确了三条规则-latest标签一般指向当前已 GA 的最新操作系统镜像版本。切换预告在把-latest标签迁移到新操作系统版本之前官方会提前发布公告给用户留出足够的时间更新 workflow。-xlarge/-large后缀这两个后缀仅存在于 macOS 镜像且只对 GitHub Actions 可用对应 GitHub 的 larger runners 能力Azure DevOps 中无法使用。从表格可以看出ubuntu-latest目前指向 Ubuntu 24.04windows-latest指向 Windows Server 2025而macos-latest指向 macOS 26 Arm64。镜像生命周期Beta → GA → 弃用README 将镜像的生命周期划分为三个阶段理解这一流程有助于判断某个镜像能否在正式流水线中使用。Beta预览阶段Beta 阶段的目的在于 GA 之前收集反馈、发现并修复潜在问题。关键事实Beta 镜像每周更新一次与 GA 相同的节奏在 Beta 镜像上运行的 workflow不适用Actions 的客户 SLA使用 Beta 镜像的用户被鼓励在本仓库创建 issue 提交反馈Beta 镜像的可用性形式可能不同公开或私有。GA正式可用阶段一个镜像要进入 GA必须满足三条硬性标准README 原文明确列出已完整经历一段 Beta 期公开或私有镜像上安装的大部分主要软件在底层操作系统上都有兼容版本Beta 期间报告的所有主要 bug 均已解决。GA 镜像受 Actions 的客户 SLA 保护并且会依据弃用指南逐步退役——仓库只支持最新 2 个版本的操作系统。例如当前同时维护 Ubuntu 22.04 与 24.04 两张 GA 镜像而 26.04 尚处于 preview。-latest迁移流程Latest Migration Process-latest标签如ubuntu-latest、windows-latest、macos-latest指向最新的稳定 OS 版本。其迁移是渐进式的整个迁移过程持续 12 个月以便用户逐步调整 workflow迁移期间使用-latest标签的 workflow 或 pipeline 可能会观测到操作系统版本发生变化若要避免意外的迁移应在 YAML 中显式指定具体版本如macos-14、windows-2022、ubuntu-22.04。这也是本文最实用的建议之一生产流水线应尽量锁定具体版本标签将-latest留给对最新环境不敏感的作业。镜像发布节奏如何跟踪变更README 提供了四条追踪镜像变更的路径在仓库的 Releases 页面查找最新发布订阅本仓库的 release 通知镜像部署开始时会创建一个pre-release部署一结束pre-release 即被转换为正式 release——订阅 release 通知即可同时收到 pre-release 与正式版通知也可通过awaiting-deployment标签跟踪即将部署的变更对高影响变更breaking changes、镜像 GA 或弃用官方会提前发布到 GitHub Changelog 博客。节奏通常每周部署一次镜像软件的更新。也就是说托管 Runner 上的软件版本每周都可能刷新这解释了为什么依赖固定版本号的构建需要setup-*系列 Action 来显式安装所需版本。软件与镜像支持策略支持策略Support PolicyREADME 明确的支持底线如下工具及其版本通常在弃用或 EOL 后 6 个月被移除同一时间最多支持2 张 GA 镜像 1 张 Beta 镜像一旦最新 OS 镜像标签 GA就开始对最旧的镜像标签启动弃用流程镜像一般包含部署时刻的最新软件包唯一例外是 Ubuntu LTS——那里主要依赖Canonical 官方仓库提供的包。多版本并存的安装策略对于流行工具镜像允许几个版本并存安装README 给出了权威的策略表工具安装策略Docker 镜像不超过 3 个最新的 LTS OS/工具版本新镜像或新版本按标准工具请求流程添加Java所有 LTS 版本Node.js3 个最新的 LTS 版本Go3 个最新的 minor 版本Python / Ruby5 个最流行的major.minor版本PyPy3 个最流行的major.minor版本.NET Core2 个最新 LTS 版本 1 个最新版本每个 feature 版本只装最新 patchUbuntu 镜像的细节见 docs/dotnet-ubuntu.mdGCC / GNU Fortran / Clang / GNU C3 个最新 major 版本Android NDK1 个最新非 LTS 2 个最新 LTS 版本Xcode每个 macOS 版本只支持一个 major 版本该 major 版本的所有 minor 版本均可用beta/RC 版本仅以“as-is”形式提供在最新可用 macOS 镜像中新 patch 发布时替换旧 patchXcode Platforms对已安装的 Xcode仅保留 3 个major.minor版本的平台工具与模拟器运行时含 beta/RC案例深化Ubuntu 上的 .NET 安装方式变更。README 策略表引用了 docs/dotnet-ubuntu.md该文档解释了从 Ubuntu 24.04 开始 .NET 安装路径发生了重大变化Ubuntu 22.04 使用 Microsoft 包仓库安装 .NET 团队构建的 deb 包而从 24.04 起Canonical 与 .NET 团队合作由 Ubuntu 自己提供 .NET 包微软不再向 24.04 的 packages.microsoft.com feed 发布 .NET 包。这带来两个实际影响其一镜像中只保留.1xxfeature bandUbuntu 只构建发布这一“兼容性 band”更高 band 可能有破坏性变更需要更高 band 时官方建议使用setup-dotnetAction 安装指定版本其二.NET MAUI 不在 Ubuntu 的 .NET 包内官方正在推进修复同样应通过setup-dotnet解决。包管理器使用Package managers usage镜像生成过程中项目使用第三方包管理器安装软件。README 给出了权威对照表操作系统包管理器第三方仓库与包UbuntuAPTdocker、Eclipse-TemurinAdoptium、Erlang、Firefox、git-lfs、gitgit-core PPA、Google Cloud CLI、Heroku、HHvm、MongoDB、Mono、MS Edge、PostgreSQL、Rpipxansible-core、yamllintWindowsChocolatey未安装第三方仓库macOSHomebrewaws-cli v2aws/homebrew-tap、azure/bicepAzure/homebrew-bicep、mongodb/brewpipxyamllintREADME 同时用 NOTE 注明第三方仓库每年都会被重新评估以确认它们仍然有用且安全——这保证了镜像供应链的持续可信度。镜像弃用策略Image Deprecation Policy弃用是一个分阶段的公告式流程新 GA OS 版本发布后最旧的镜像标签开始进入弃用流程弃用流程始于一次设定弃用日期的公告临近日期时GitHub 开始对该镜像进行定期 brownout有计划地短暂不可用期间仓库会置顶 Announcement 提醒用户最终镜像被正式弃用不再可用。预安装策略Preinstallation Policy决定“预装什么”的六条指导原则流行度Popularity广泛使用的工具与生态优先最新技术Latest Technology较新版本的工具优先弃用Deprecation已 EOL 的工具与版本不加入许可Licensing仅接受 MIT、Apache 或 GNU 许可时间与空间Time Space评估预装工具节省的时间与占用的镜像空间支持Support若某工具需要同时维护多个版本会评估其维护成本。FAQ 中进一步说明部分工具部署时始终安装最新版另一部分则固定到特定版本——两者结合正是“最新”与“可复现”之间的平衡。默认版本更新策略Default Version Update Policy一般而言新版本装入镜像后默认版本更新会在部署前 2 周发布公告对潜在危险的更新公告与部署之间的时间线可延长至1 个月。如何与仓库互动Issues提交 bug 报告、请求新增/更新工具使用合适的模板创建 issueDiscussions分享对镜像配置、预装软件的想法或提出新思路前往 GitHub Community 的 Actions 分类创建讨论创建前请先搜索确认无相似主题。常见问题FAQsREADME 的 FAQ 章节回答了六个高频问题这里完整整理GitHub Actions 与 Azure DevOps 可用的镜像一样吗可用性相同但弃用策略可能不同细节分别见各自官方文档。如何知道我的构建用了哪个镜像版本镜像部署通常需要 23 天且main分支的文档只在部署完成后才更新。要确认某次构建实际使用的镜像版本与软件版本查看 GitHub Actions 的Set up job步骤日志或 Azure DevOps 的Initialize job步骤日志即可。会提供其他 Linux 发行版吗官方不计划提供。推荐使用 Docker 在托管 Runner 镜像上构建其他发行版环境或者使用 self-hosted runners 完全自定义虚拟机镜像。如何为 macOS 源码做贡献macOS 源码就在本仓库且公开但 macOS 镜像生成的 CI 目前还不支持外部贡献暂不接受 pull request在此期间请通过 issue 提出工具请求。GitHub 如何决定镜像上装哪些工具部分工具部署时安装最新版部分固定版本详见上文“预安装策略”。如何请求预装新工具先创建 issue 并获得批准再提交 pull request。自定义镜像应该用哪个分支官方强烈建议使用main分支构建。仓库中的多个分支和 release 只是“文档里程碑”反映某时间点镜像内的软件版本当前构建不是幂等的——用特定 tag 构建 runner 镜像不保证成功。纵深如何基于本仓库构建自己的 Runner 镜像README 指向的 docs/create-image-and-azure-resources.md 给出了完整构建流程本文结合源码做要点深化详细步骤以该文档为准。底层原理Packer Azure构建的核心是Packer仓库要求 1.8.2 或更高每个镜像由一份HCL2 Packer 模板描述指定在 Azure 中构建、安装软件与准备磁盘的步骤。流程为Packer 通过 Azure CLI 初始化与 Azure 订阅的连接创建临时资源资源组、网络接口、基于模板中“干净”镜像的虚拟机→ 通过 SSHLinux或 WinRMWindows连接虚拟机并逐一执行安装步骤 →任一步骤失败则中止并销毁临时 VM→ 全部成功后从临时 VM 的磁盘创建托管镜像并删除 VM。Packer 还会尽力清理其创建的临时资源。源码佐证GenerateResourcesAndImage辅助函数helpers/GenerateResourcesAndImage.ps1内部用Get-PackerTemplate将ImageType枚举Windows2022、Windows2025、Windows2025_vs2026、Ubuntu2204、Ubuntu2404、Ubuntu2604映射到具体模板文件例如Ubuntu2404→build.ubuntu-24_04.pkr.hcl、Windows2022→build.windows-2022.pkr.hcl并返回 Packer-only所需的 BuildName 与image_os值如ubuntu24、win22。构建 Agent 准备构建 Agent运行 Packer 的机器任意 Windows/Linux 物理机或虚拟机也可用 Azure VM需安装Packer 1.8.2Windows 可用choco install packerGitWindows 可用choco install git -params /GitAndUnixToolsOnPathPowerShell 5.0Linux 需通过微软 Linux 软件仓库安装powershell包Azure CLIWindows 可用Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows ...安装。手动生成镜像克隆仓库后用 PowerShell 导入辅助脚本并调用git clone 本仓库地址 Set-Location runner-images Import-Module .\helpers\GenerateResourcesAndImage.ps1然后调用GenerateResourcesAndImage四个必填参数为SubscriptionIdAzure 订阅 ID、ResourceGroupName存放产物的资源组必须已存在、AzureLocation如 East US、ImageType有效值即上文枚举的六种。该函数会自动创建全部 Azure 资源并启动 Packer 构建。常用可选参数还包括Tags为资源打标签的 HashTable、AzureClientId/AzureClientSecret/AzureTenantId非交互式认证、RestrictToAgentIpAddress仅允许构建 Agent 公网 IP 访问临时 VM、ManagedImageName默认Runner-Image-{ImageType}、OnError默认ask。完整参数用get-help GenerateResourcesAndImage -Detailed查看。网络安全与认证公网模式若构建 Agent 在订阅之外会使用公共网络接口与公网 IP需确保防火墙放行 WinRMTCP 5986与 SSHTCP 22既包含 Agent 出站也包含临时 VM 入站设置RestrictToAgentIpAddress$true可把访问限制在 Agent 公网 IP。私有网络模式Agent 与临时 VM 在同一订阅时可设置环境变量VNET_RESOURCE_GROUP、VNET_NAME、VNET_SUBNET让 Packer 走私有虚拟网络。认证Packer 使用 Service Principal 访问 Azure。GenerateResourcesAndImage默认通过Connect-AzAccount交互式认证非交互场景需自行创建具备所选订阅读写权限的 Service Principal并传入AzureClientId、AzureClientSecret、AzureTenantId。文档还给出了用New-AzADServicePrincipal创建 SP 并授予Contributor角色的完整 PowerShell 示例源码层面函数还支持UseOidcGitHub Actions OIDC 联邦凭据认证与OidcRequestToken/OidcRequestUrl参数。生成机的部署镜像生成后用 helpers/CreateAzureVMFromPackerTemplate.ps1 从托管镜像创建 VMImport-Module .\helpers\CreateAzureVMFromPackerTemplate.ps1 CreateAzureVMFromPackerTemplate -SubscriptionId {YourSubscriptionId} -ResourceGroupName {ResourceGroupName} -ManagedImageName Runner-Image-Ubuntu2204 -VirtualMachineName testvm1 -AdminUsername shady1 -AdminPassword SomeSecurePassword1 -AzureLocation eastus自动化生成CI/CD 集成在流水线中直接调用 Packer先安装 Azure 插件再构建packer plugins install github.com/hashicorp/azure 2.2.1 packer build -only $BuildName.* -var subscription_id$SubscriptionId -var client_id$ClientId -var client_secret$ClientSecret -var install_password$InstallPassword -var location$Location -var image_os$ImageOS -var managed_image_name$ImageName -var managed_image_resource_group_name$ImageResourceGroupName -var tenant_id$TenantId $TemplatePath参数说明BuildName为模板build{}块中定义的构建名如ubuntu-24_04、windows-2025InstallPassword是软件安装用户密码仅 WindowsImageOS是临时 VM 的操作系统类型如ubuntu24、win25TemplatePath指向模板目录如images/windows/templates。必需变量模板变量 ↔ 环境变量的对应关系均可在 images/ubuntu/templates/variable.ubuntu.pkr.hcl 中找到默认值定义模板变量环境变量说明subscription_idARM_SUBSCRIPTION_ID执行构建的订阅client_idARM_CLIENT_ID与 builder 关联的 AD Service Principalclient_secretARM_CLIENT_SECRETSP 的密码/密钥设置了client_cert_path或client_jwt时可省略client_cert_pathARM_CLIENT_CERT_PATH包含 SP 证书与私钥的 PEM 文件路径设置了client_secret或client_jwt时可省略client_jwtARM_CLIENT_JWT用于联合/工作负载身份认证的 bearer JWT如 Azure DevOps workload identity federation设置了client_secret或client_cert_path时可省略locationARM_RESOURCE_LOCATION构建 VM 所在的 Azure 数据中心managed_image_resource_group_nameARM_RESOURCE_GROUP存放最终产物的资源组可选变量managed_image_name默认Runner-Image-{{ImageType}}、build_resource_group_name指定已存在的构建资源组默认会创建并销毁临时资源组、object_id、tenant_id为空时按subscription_id反查、temp_resource_group_name临时资源组名为空则随机分配、private_virtual_network_with_public_ip、virtual_network_name使用既有 VNet、不分配公网 IP、virtual_network_resource_group_name、virtual_network_subnet_name。Builder 变量azure-armbuilder 专用可覆盖以调整构建性能见 images/ubuntu/templates/source.ubuntu.pkr.hclvm_size构建用 VM 规格默认Standard_D4s_v4、image_os临时 VM 的 OS 类型、image_version启动的 OS 版本默认latest。此外 locals.ubuntu.pkr.hcl 定义了各image_os对应的 Azure Marketplace 镜像 SKU如ubuntu24→canonical:ubuntu-24_04-lts:server与 75GB 的默认系统盘大小。Toolset可裁剪的软件配置部分预装软件的配置集中在toolset.json中如 images/ubuntu/toolsets/toolset-2404.json定义 Ruby、Python、Go 版本列表、PowerShell 模块与 VS 组件等。以 toolset-2404.json 为例toolcache段声明了 Python3.10.~3.14.、PyPy3.9~3.11、node22.、24.、go1.24.~1.26.默认 1.24.、Ruby3.2.~4.0.、CodeQL等版本通配符java段声明默认 JDK 17、全部 LTS 版本 8/11/17/21/25 及 Maven 3。README 说明若某些工具用不到可以修改这些文件以缩短构建时间、缩小镜像体积。Post-generation 脚本修复用户态环境镜像生成过程中创建的用户在最终镜像中不存在因此与用户主目录相关的配置和目录权限需要修正。脚本位于仓库post-gen目录Ubuntu 在 images/ubuntu/assets/post-genWindows 在 images/windows/assets/post-gen构建时会被复制到镜像中Linux/opt/post-generation、WindowsC:\post-generation。注意Linux 默认用户应具备 sudo 权限。运行方式在 Azure 部署的 VM 上执行# Ubuntu sudo su -c find /opt/post-generation -mindepth 1 -maxdepth 1 -type f -name *.sh -exec bash {} \;# Windows Get-ChildItem C:\post-generation -Filter *.ps1 | ForEach-Object { $_.FullName }Ubuntu 侧脚本以当前仓库实际文件为准cleanup-logs.sh清理构建过程日志、environment-variables.sh将默认用户主目录相关环境变量中的$HOME替换为默认用户的 home、systemd-linger.shsystemd linger 配置。Windows 侧脚本GenerateIISExpressCertificate.ps1生成并导入 IIS Express HTTPS 证书、InternetExplorerConfiguration.ps1关闭 IE 增强安全配置、Msys2FirstLaunch.ps1初始化 MSYS2 bash 用户配置文件、VSConfiguration.ps1执行 Visual Studio 初始配置。结语runner-images 仓库的价值在于把“托管 Runner 上装了什么、为什么装、什么时候换”这一黑盒变成了完全透明的开源工程。通过本文你可以根据支持矩阵与标签方案选对镜像标签、用显式版本锁定规避-latest迁移风险、理解软件预装与弃用背后的策略逻辑以及借助 Packer 模板与辅助脚本在 Azure 上构建、定制属于自己的 Runner 镜像。若需进一步动手优先阅读 docs/create-image-and-azure-resources.md并以main分支为构建基准。【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考