# actions/runner-images: the source behind GitHub-hosted runner VMs > This repository holds the source used to build the VM images behind GitHub-hosted runners and Microsoft-hosted Azure Pipelines agents. It is infrastructure source, not a tool you install on your laptop, and the README is explicit about which labels map to which OS. **actions/runner-images** — GitHub Actions runner images - Repository: https://github.com/actions/runner-images - Stars: 13,405 · Forks: 3,878 - Language: PowerShell - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/actions-runner-images ## What actions/runner-images actually is, and who needs it The README opens by describing the repository as the source code used to create the VM images for GitHub-hosted runners used for Actions, and for Microsoft-hosted agents used for Azure Pipelines. That sentence is the whole scope. The repository does not run your job, does not schedule anything, and does not ship a CLI that a developer installs to get a faster build. It is the definition layer: the scripts and image configuration that turn a base operating system into the machine your workflow lands on. The audience is therefore narrow and specific. Platform engineers who maintain self-hosted runners and want parity with the hosted environment are the primary readers, because they can build from the same source rather than guessing which packages GitHub preinstalls. Azure Pipelines administrators who run Microsoft-hosted agents have the same interest for the same reason. A third group is subtler: anyone debugging a workflow that passes locally and fails in CI because a tool version differs. Reading the image definition is how you find out what is actually on the machine. If your only goal is to write a YAML workflow, this repository is not on your critical path. ## How the image definitions are organised The top level of the repository separates concerns cleanly. The images/ directory holds per-OS image definitions, docs/ holds the build instructions, helpers/ holds shared scripts, and schemas/ holds the schema files that validate the image configuration. images.CI/ sits alongside images/ and appears to carry the CI-side image configuration used to build and validate the definitions. The primary language is PowerShell, which follows from the Windows-heavy portion of the matrix and from the provisioning scripts that install software into each image. The README's Available Images table is the operational core. Each row pairs an OS and architecture with a YAML label and a link to a per-image readme that lists included software. Ubuntu 24.04 x64 carries both ubuntu-latest and ubuntu-24.04, so a workflow pinned to ubuntu-latest is really pinned to whatever the project currently considers the GA Ubuntu release. macOS 26 Arm64 maps to macos-latest, macos-26 and macos-26-xlarge, while macOS 26 x64 maps to macos-latest-large, macos-26-intel and macos-26-large. The -large and -xlarge suffixes are documented as unique to macOS images and available only for GitHub Actions, which is a real constraint if you are on Azure Pipelines and expect the same label to exist. The data flow is one-directional. A definition in images/ describes the base OS, the architecture and the software to install. The build produces a VM image, and the image is published under a dated release tag such as win22/20260913.307 or win11-arm64/20260920.174. Labels are the user-facing alias on top of those dated images, and the label scheme section states that the -latest label generally tracks the latest GA OS version, with an announcement and lead time before it moves to a new release. That announcement window is the mechanism that protects workflows from silently changing OS underneath them. ## Building an image from this source, and the label decision that comes first There is no package to install. The README states that to build a VM machine from the repository's source you should follow the instructions in docs/create-image-and-azure-resources.md. That document is the entry point, and the repository does not reproduce its contents in the README, so the exact build commands live there rather than here. What the README does give is the mapping you need before you start. Pick the image whose label matches the environment you are trying to reproduce, then read its per-image readme for the installed software list. For example, the Ubuntu 24.04 row links to images/ubuntu/Ubuntu2404-Readme.md, and the Ubuntu 26.04 row links to images/ubuntu/Ubuntu2604-Readme.md. Those files are where you confirm a toolchain version before you commit to a base image. The first real decision is a workflow edit, not a build. The README's table is the source of the label values, and the label scheme says the -latest label generally tracks the latest GA OS image version. Reading the table tells you that ubuntu-24.04 and ubuntu-latest currently point at the same Ubuntu release, so choosing the versioned label removes one source of drift. The same logic applies on the Windows side, where windows-2022 is a fixed label while windows-latest currently resolves to Windows Server 2025. If you are building images yourself, the build path starts from docs/create-image-and-azure-resources.md and the definitions under images/, and the dated release tags such as win22/20260913.307 show the naming pattern the project uses for published builds. ## Deprecation, label drift and the macOS architecture split The most concrete limitation is visible directly in the table. macOS 14 x64 and macOS 14 Arm64 both carry a deprecated badge pointing at issue 13518. A deprecated image is not removed immediately, but it is on a path out, and a workflow pinned to macos-14 will eventually need to move. The README does not state the removal date, and it does not document a rollback path if a new image breaks your build. That silence matters: the label scheme promises lead time before -latest moves, but there is no documented mechanism in the README for pinning to a specific dated image tag from a workflow. The macOS architecture split is the second trap. macOS 26 x64 and macOS 26 Arm64 are separate rows with separate labels, and the -large and -xlarge suffixes exist only on the macOS images and only for GitHub Actions. A team that standardises on xlarge labels for GitHub Actions and then tries the same label on Azure Pipelines will not find it. The README states the restriction plainly rather than hiding it, which is better than the alternative, but it still means cross-platform label portability is not a thing here. A third constraint is architectural. Because the repository is the source of prebuilt images rather than a runtime, you cannot patch a hosted runner. If a package version on ubuntu-24.04 is wrong for your project, your options are to pin a different label, install the version yourself in a workflow step, or build and host your own image. The repository gives you the definitions to do the third, but it does not make the first two unnecessary. ## Where self-hosted runner tooling differs The natural comparison is actions/runner, the repository that contains the runner application itself. The two are often confused because both live under the actions organisation and both relate to CI execution. The difference in approach is clean: actions/runner is the agent binary that connects to GitHub, registers with a repository or organisation, and executes jobs on a machine you already have. actions/runner-images is the definition of the machine that GitHub provides when you do not bring your own. That distinction determines which one you adopt. If you are standing up a self-hosted runner on your own hardware, you install the runner from actions/runner and then decide what to put on the host. If you want the host to look like a GitHub-hosted runner, you read the image definitions here to see what that means in practice. The two repositories are complementary rather than competing, and neither replaces the other. A team that adopts actions/runner but ignores the image definitions will end up maintaining an environment that drifts from the hosted one, which is exactly the situation the per-image readmes exist to prevent. ## Maintenance cadence, licence and upgrade cost The repository is not archived, and the last push was on 2026-09-21. Recent releases follow a dated naming pattern, with win22/20260913.307, win11-vs2026-arm64/20260920.164 and win11-arm64/20260920.174 all published on 2026-09-21. The version numbers inside the tags track the image build date, so the release list doubles as a changelog of when each image was rebuilt. The licence is MIT, which is permissive and places few obligations on reuse of the definitions. The README does not discuss licence implications, and this is not legal advice: if you redistribute built images or bundle the scripts into a commercial product, read the LICENSE file and check the licences of the software each image installs, since those are separate from the repository's own MIT terms. The upgrade cost is the part teams underestimate. Because labels move, an image update can change a tool version without any change on your side. The README's announcement policy for -latest label moves is the only mitigation it documents, and it applies to the floating labels rather than to the versioned ones. If your build is sensitive to compiler or runtime versions, the versioned labels are the cheaper long-term choice, and the per-image readmes are where you verify what changed before you move. ## Conclusion Adopt this repository if you maintain a self-hosted runner fleet or an Azure DevOps agent pool and want to reproduce the same image definitions GitHub publishes, or if you need to read the exact software manifest behind a label such as ubuntu-24.04 before pinning a workflow to it. Do not adopt it if you only need a runner: the repository is the build source, and the README points to GitHub's hosted-runner documentation for actually using one. Before committing, verify which label your workflow currently resolves to, check whether that image is marked deprecated in the Available Images table, and read docs/create-image-and-azure-resources.md to confirm the build path matches your Azure subscription and tooling. ## FAQ ### What is the difference between actions/runner-images and actions/runner? actions/runner-images contains the source used to build the VM images for GitHub-hosted runners and Microsoft-hosted Azure Pipelines agents. The runner application that executes jobs on a machine is a separate concern, and the README describes this repository only as the image source. ### Which YAML label should I use for Ubuntu in a workflow? The Available Images table maps Ubuntu 24.04 x64 to both ubuntu-latest and ubuntu-24.04, and Ubuntu 22.04 x64 to ubuntu-22.04. The README states that the -latest label generally tracks the latest GA OS image version, so a versioned label is the more stable target. ### Are the macOS -large and -xlarge labels available everywhere? No. The README states that the -xlarge and -large suffixes are unique to macOS images and are only available for GitHub Actions, with a link to GitHub's larger runners documentation. They do not apply to the Ubuntu or Windows rows. ### How do I build a VM image from this repository? The README states that to build a VM machine from the repository's source you should follow the instructions in docs/create-image-and-azure-resources.md. The README itself does not reproduce those build steps. ### Is any image in the list deprecated? Yes. macOS 14 x64 and macOS 14 Arm64 both carry a deprecated badge linking to issue 13518 in the Available Images table. The README does not state when those images will be removed. ## Sources - [actions/runner-images on GitHub](https://github.com/actions/runner-images) - [Issues](https://github.com/actions/runner-images/issues) - [License: MIT](https://github.com/actions/runner-images/blob/main/LICENSE) - [README](https://github.com/actions/runner-images/blob/main/README.md) - [Releases](https://github.com/actions/runner-images/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/actions-runner-images