runner-images

Product Introduction

1. Definition: GitHub Actions runner-images is a public repository containing the source code and configuration files used to build the standardized virtual machine (VM) images that power GitHub-hosted runners for GitHub Actions and Microsoft-hosted agents for Azure Pipelines. It is a foundational infrastructure-as-code project for CI/CD environments.
2. Core Value Proposition: It exists to provide developers and teams with consistent, secure, and pre-configured build environments, eliminating the overhead of managing and maintaining self-hosted CI/CD infrastructure. Its core value is in offering reliable, up-to-date, and tool-rich environments for automated software development workflows.

Main Features

1. Multi-Platform Image Definitions: The repository provides detailed provisioning scripts and configuration for a wide range of operating systems and architectures. This includes Ubuntu (x64 and Arm64), macOS (Intel and Apple Silicon), and Windows Server/Client (x64 and Arm64). Each image definition specifies the exact software packages, versions, and system configurations.
2. Automated Weekly Software Updates: The VM images are rebuilt and deployed on a weekly cadence. This automated update process ensures that all pre-installed tools, language runtimes (like Node.js, Python, .NET), security patches, and system packages are kept current, reducing security vulnerabilities and compatibility issues in CI/CD pipelines.
3. Comprehensive Pre-installed Toolchain: The images come with a vast array of development tools pre-installed. This includes multiple versions of programming languages (Java LTS, Python, Go), build tools (Gradle, Maven), cloud CLIs (AWS, Azure, GCP), container tools (Docker, Docker Compose), and database clients. This is managed via package managers like APT, Homebrew, and Chocolatey, with a defined version support policy.
4. Structured Release and Lifecycle Management: The project follows a clear Beta and General Availability (GA) release process for new OS versions. It maintains a transparent deprecation policy, supporting a maximum of two GA images per OS family. The migration of the -latest label is a gradual, announced process, giving users time to adapt their workflows.

Problems Solved

1. Pain Point: Eliminates "works on my machine" syndrome and environment drift in continuous integration. Manually configuring and maintaining identical, secure build environments across a team or organization is time-consuming, error-prone, and difficult to scale.
2. Target Audience: Software development teams of all sizes using GitHub Actions or Azure Pipelines; Open-source project maintainers; DevOps and platform engineers seeking standardized build environments; Developers who need to test across multiple OS platforms and tool versions without local setup.
3. Use Cases: Running automated tests across Linux, macOS, and Windows in a single workflow; Building and deploying cross-platform applications (e.g., Electron, .NET Core); Creating CI/CD pipelines that require specific, complex toolchains (like Android NDK or Xcode) without manual installation; Ensuring security compliance by using centrally managed, patched base images.

Unique Advantages

1. Differentiation: Unlike generic cloud VM images or self-configured runners, runner-images are purpose-built for CI/CD, curated by GitHub, and tightly integrated with GitHub Actions. Compared to using plain Docker containers, these images offer bare-metal performance for macOS and come pre-loaded with a much broader, deeper set of tools out-of-the-box, saving significant pipeline time.
2. Key Innovation: The project's open-source nature is its key innovation. The entire image generation process is transparent and version-controlled. Users can audit the installed software, propose changes via issues, and even fork the repository to build custom, derivative images for their own self-hosted runners, ensuring complete control and reproducibility.

Frequently Asked Questions (FAQ)

1. What is the difference between ubuntu-latest, ubuntu-24.04, and ubuntu-22.04 in GitHub Actions? ubuntu-latest is a floating label that points to the newest stable Ubuntu version (currently 24.04). ubuntu-24.04 and ubuntu-22.04 are pinned labels that will always use those specific OS versions, providing stability and preventing unexpected changes from an OS upgrade in your CI/CD pipeline.
2. How can I see what software versions are installed on the runner my job is using? Check the "Set up job" step log in your GitHub Actions workflow run. It lists the exact runner image version (e.g., 20250126.1) and links to the release notes in the runner-images repository, which detail every installed tool and its version for that specific image build.
3. Can I request a new tool to be added to the GitHub Actions runner image? Yes, you must open a new Issue in the runner-images GitHub repository using the provided template. The request is evaluated against a public Preinstallation Policy, which considers factors like tool popularity, licensing, maintenance cost, and space impact before approval.
4. When are older runner images like ubuntu-20.04 deprecated? Images begin deprecation once a newer OS version reaches GA. The policy supports a maximum of two GA images. Deprecation involves an announcement, a period of scheduled brownouts (where the image is temporarily unavailable), and finally full removal. This process is documented via announcements in the repository.
5. Why can't I contribute a pull request to update software on the macOS runner images? While the macOS source code is open, the internal CI system that builds the official macOS images does not yet support external contributions. Tool updates for macOS must be requested via an Issue. The team is working to enable full external contribution for macOS in the future.