runner-images
SHA-256GitHub 官方托管运行器镜像的构建源码,涵盖 Ubuntu、Windows、macOS 等环境,按周更新补丁与工具链。
GitHub 官方 CI 虚拟机镜像的配方仓库。
核心功能
- 覆盖 Ubuntu、Windows Server、Windows 11 Arm64、macOS 与 Xcode 预览镜像
- 同时提供 x64 与 arm64 双架构版本
- 预装数十种语言运行时、SDK、CLI 工具,开箱即用
- 按周更新安全补丁与软件版本,无需自行维护
- 公开 GA/Beta 晋级规则,升级前提前公告
避坑指南
- •镜像中的预装软件由官方统一决定,你不能随意增删;临时安装的工具在下次任务中不会保留。Beta 镜像不在 Actions 的 SLA 保障范围内,不建议用于正式生产流程。macOS 的 -large 与 -xlarge 后缀仅限 GitHub Actions 且需要付费的 larger runner。当 -latest 指向新系统版本时,原有依赖旧系统的脚本可能报错,务必提前锁定具体版本号而不是长期依赖 -latest。另外该仓库不面向普通用户提供本地安装包,只是构建配方。
适用场景
- 为 GitHub Actions 工作流挑选合适的运行器镜像标签
- 为 Azure Pipelines 的 Microsoft 托管代理准备构建环境
- 本地或私有云按官方配方复刻同款 CI 虚拟机
- 排查 CI 构建失败时核对镜像内预装软件版本
详细介绍
runner-images 是 GitHub 官方开源的虚拟机镜像构建仓库,为 GitHub Actions 托管运行器和 Azure Pipelines 的 Microsoft 托管代理提供底层系统环境。它覆盖 Ubuntu 22.04/24.04/26.04(x64 与 arm64)、Ubuntu Slim、Windows Server 2022/2025、Windows 11 Arm64,以及 macOS 14/15/26 和 Xcode 预览镜像,预装数十种语言运行时、SDK 与命令行工具,并按周更新安全补丁和软件版本。相比自己维护 CI 基础镜像或使用社区 Docker 镜像,本项目由官方持续维护、有 SLA 保障,`-latest` 标签语义清晰,升级前会提前公告,团队无需自行负责补丁管理。仓库同时公开 GA/Beta 镜像的晋级标准,用户可通过 Issue 申请新增软件或反馈问题。
常见问题与排障 (2)
操作指南适用于 Windows Server 2025 和 Ubuntu 24.04 的第 2 代 VM 的正确 Azure Marketplace SKU 是什么?
要在 Azure 上使用第 2 代 VM 映像,请更新部署或映像构建配置中的 SKU 引用:
**Windows Server 2025:** 将 SKU 从 2025-Datacenter 更改为 2025-Datacenter-g2。-g2 后缀用于显式选择第 2 代映像。
**Ubuntu 24.04 LTS:** 将 SKU 从 server-gen1 更改为 server。标准 server SKU 是 Ubuntu 24.04 的官方默认 SKU,本身即为第 2 代——必须移除 -gen1 变体。
更新后,请重新部署或重新构建映像以启用 Gen2 支持(UEFI 启动、Trusted Launch 和更大规格的 VM 等功能需要此支持)。
故障排除在 Ubuntu runner 从 Maven 3.9.16 升级到 3.10.0 后,如何修复 Maven 构建或 Maven Central 部署失败?
Maven 3.10.0 引入了更严格的 POM 验证,因此在 Maven 3.9.16 下可正常工作的构建可能会失败,或产生部署错误,例如 "Bundle has content that does NOT have a .pom file."。作为变通方案,在 CI 中固定使用 Maven 3.9.16,而不是使用 ubuntu-24.04 上预装的 Maven 版本。对于 Azure DevOps,在 Maven 构建前添加以下内容:
- bash: |
set -euo pipefail
curl -fsSL https://archive.apache.org/dist/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz -o /tmp/maven.tar.gz
mkdir -p "$HOME/tools"
tar -xzf /tmp/maven.tar.gz -C "$HOME/tools"
echo "##vso[task.prependpath]$HOME/tools/apache-maven-3.9.16/bin"
使用 mvn -version 验证,然后运行部署。在 GitHub Actions 上,将 Azure DevOps 的 prepend 命令替换为:
echo "$HOME/tools/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
永久修复方案是更新 POM,使其与 Maven 3.10.0 验证兼容,或者在那之前一直将 Maven 固定为 3.9.16。
标签
快速上手
安装软件
双击下载的安装程序,按提示完成安装
打开仓库 README 的 Available Images 表格,按操作系统和 CPU 架构找到目标镜像
在 workflow 的 runs-on 字段填入对应的 YAML 标签,例如 ubuntu-latest 或 windows-2022
点击表格中 Included Software 链接,确认镜像内是否已包含所需的语言与工具版本
- 打开仓库 README 的 Available Images 表格,按操作系统和 CPU 架构找到目标镜像
- 在 workflow 的 runs-on 字段填入对应的 YAML 标签,例如 ubuntu-latest 或 windows-2022
- 点击表格中 Included Software 链接,确认镜像内是否已包含所需的语言与工具版本
已提供 SHA-256 校验码,下载后可自行核对文件完整性
该校验码提取自 GitHub 官方 Release 页面
SHA256 校验码
cb1cbd1ef895aacf72d92269c48b5df5445aab63444b56a95966b499df2f0cd4该校验码提取自 GitHub Release 页面,下载后请自行核对文件完整性
本平台所有 SHA-256 校验码均提取自项目在 GitHub 官方 Release 页面发布的文件,未做任何修改。你可以通过 GitHub Releases 页面自行验证。
开源透明
查看 GitHub 源码卸载说明
本仓库本身只是镜像配方源码,无需在本机安装。如果不再使用某个镜像标签,只需在 workflow 文件中把 runs-on 改成其他标签或自建 self-hosted runner;如需删除自己按配方构建的 Azure 资源,请在 Azure 门户中删除对应的资源组和虚拟机,避免持续计费。
无额外依赖
下载后即可直接使用,无需安装其他运行环境
遇到问题?查看下方 FAQ
2 FAQs