R

runner-images

SHA-256
13.3k stars·开发工具·已提供 SHA-256 校验码,下载后可自行核对文件完整性

GitHub 官方托管运行器镜像的构建源码,涵盖 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 等功能需要此支持)。

来源 Issue #13939
故障排除
在 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。

来源 Issue #14883

标签

GitHub ActionsCI/CD虚拟机镜像持续集成DevOpsAzure Pipelines

快速上手

1

下载安装包

点击上方按钮下载对应系统的安装包

2

安装软件

双击下载的安装程序,按提示完成安装

3

打开仓库 README 的 Available Images 表格,按操作系统和 CPU 架构找到目标镜像

4

在 workflow 的 runs-on 字段填入对应的 YAML 标签,例如 ubuntu-latest 或 windows-2022

5

点击表格中 Included Software 链接,确认镜像内是否已包含所需的语言与工具版本

安装指引
  1. 打开仓库 README 的 Available Images 表格,按操作系统和 CPU 架构找到目标镜像
  2. 在 workflow 的 runs-on 字段填入对应的 YAML 标签,例如 ubuntu-latest 或 windows-2022
  3. 点击表格中 Included Software 链接,确认镜像内是否已包含所需的语言与工具版本
文件完整性

已提供 SHA-256 校验码,下载后可自行核对文件完整性

该校验码提取自 GitHub 官方 Release 页面

SHA256 校验码

cb1cbd1ef895aacf72d92269c48b5df5445aab63444b56a95966b499df2f0cd4

该校验码提取自 GitHub Release 页面,下载后请自行核对文件完整性

本平台所有 SHA-256 校验码均提取自项目在 GitHub 官方 Release 页面发布的文件,未做任何修改。你可以通过 GitHub Releases 页面自行验证。

运维指引

卸载说明

本仓库本身只是镜像配方源码,无需在本机安装。如果不再使用某个镜像标签,只需在 workflow 文件中把 runs-on 改成其他标签或自建 self-hosted runner;如需删除自己按配方构建的 Azure 资源,请在 Azure 门户中删除对应的资源组和虚拟机,避免持续计费。

无额外依赖

下载后即可直接使用,无需安装其他运行环境

项目信息
开源协议MIT
最后更新2026-10-16 13:02:45
GitHub 仓库官方网站

遇到问题?查看下方 FAQ

2 FAQs

相似推荐