GitHub Actions Runner Images

Table of Contents

• About
• Available Images
• Announcements
• Image Releases
• Software and Image Support
• How to Interact with the Repo
• FAQs

About

This repository contains the source code used to create the VM images for GitHub-hosted runners used for Actions, as well as for Hetzner Cloud. To build a VM machine from this repo's source, see the instructions.

Available Images

Image	Included Software	Statuses of Latest Image Release	Latest Release
Ubuntu 24.04	ubuntu-24.04
Ubuntu 22.04	ubuntu-22.04

Announcements

See notable upcoming changes by viewing issues with the Announcement label.

Image Releases

How to best follow along with changes

1. Find the latest releases for this repository here.

2. Subscribe to the releases coming out of this repository, instructions here.

3. Upcoming changes: A pre-release is created when the deployment of an image has started. As soon as the deployment is finished, the pre-release is converted to a release. If you have subscribed to releases, you will get notified of pre-releases as well.

   • You can also track upcoming changes using the awaiting-deployment label.

4. For high impact changes, we will post these in advance to the GitHub Changelog on our blog and on X.

   • Ex: breaking changes, GA or deprecation of images

Cadence

• We typically deploy weekly updates to the software on the runner images.

Software and Image Support

Support Policy

• Tools and versions will typically be removed 6 months after they are deprecated or have reached end-of-life

• We support (at maximum) 2 GA images and 1 beta image at a time. We begin the deprecation process of the oldest image label once the newest OS image label has been released to GA.

• The images generally contain the latest versions of packages installed except for Ubuntu LTS where we mostly rely on the Canonical-provided repositories.

• Popular tools can have several versions installed side-by-side with the following strategy:

Tool name	Installation strategy
Docker images	not more than 3 latest LTS OS\tool versions. New images or new versions of current images are added using the standard tool request process
Java	all LTS versions
Node.js	3 latest LTS versions
Go	3 latest minor versions
Python Ruby	5 most popular major.minor versions
PyPy	3 most popular major.minor versions
.NET Core	2 latest LTS versions and 1 latest version. For each feature version only latest patch is installed. Note for Ubuntu images see details.
GCC GNU Fortran Clang GNU C++	3 latest major versions
Android NDK	1 latest non-LTS, 2 latest LTS versions
Xcode	- only one major version of Xcode will be supported per macOS version - all minor versions of the supported major version will be available - beta and RC versions will be provided "as-is" in the latest available macOS image only no matter of beta/GA status of the image - when a new patch version is released, the previous patch version will be replaced

Package managers usage

We use third-party package managers to install software during the image generation process. The table below lists the package managers and the software installed.

Note

Third-party repositories are re-evaluated every year to identify if they are still useful and secure.

Operating system	Package manager	Third-party repos and packages
Ubuntu	APT	Eclipse-Temurin (Adoptium) Erlang Firefox git-lfs git Google Cloud CLI Heroku HHvm MongoDB Mono MS Edge PostgreSQL R
Ubuntu	APT	containers (Ubuntu 20 only) docker (Ubuntu20 0nly) Eclipse-Temurin (Adoptium) Erlang Firefox git-lfs git Google Cloud CLI Heroku HHvm MongoDB Mono MS Edge PostgreSQL R
Ubuntu	APT	Eclipse-Temurin (Adoptium) Erlang Firefox git-lfs git Google Cloud CLI Heroku HHvm MongoDB Mono MS Edge PostgreSQL R
Ubuntu	APT	Eclipse-Temurin (Adoptium) Erlang Firefox git-lfs git Google Cloud CLI Heroku HHvm MongoDB Mono MS Edge PostgreSQL R
	pipx	ansible-core yamllint
Windows	Chocolatey	No third-party repos installed
macOS	Homebrew	aws-cli v2 azure/bicep mongodb/brew
	pipx	yamllint

Image Deprecation Policy

• Images begin the deprecation process of the oldest image label once a new GA OS version has been released.
• Deprecation process begins with an announcement that sets a date for deprecation
• As it gets closer to the date, GitHub begins doing scheduled brownouts of the image
• During this time there will be an Announcement pinned in the repo to remind users of the deprecation.
• Finally GitHub will deprecate the image and it will no longer be available

Preinstallation Policy

In general, these are the guidelines we follow when deciding what to pre-install on our images:

• Popularity: widely-used tools and ecosystems will be given priority.
• Latest Technology: recent versions of tools will be given priority.
• Deprecation: end-of-life tools and versions will not be added.
• Licensing: MIT, Apache, or GNU licenses are allowed.
• Time & Space on the Image: we will evaluate how much time is saved and how much space is used by having the tool pre-installed.
• Support: If a tool requires the support of more than one version, we will consider the cost of this maintenance.

Default Version Update Policy

• In general, once a new version is installed on the image, we announce the default version update 2 weeks prior to deploying it.
• For potentially dangerous updates, we may extend the timeline up to 1 month between the announcement and deployment.

How to Interact with the Repo

• Issues: To file a bug report, or request tools to be added/updated, please open an issue using the appropriate template
• Discussions: If you want to share your thoughts about image configuration, installed software, or bring a new idea, please create a new topic in a discussion for a corresponding category. Before making a new discussion please make sure no similar topics were created earlier.
• For general questions about using the runner images or writing your Actions workflow, please open requests in the GitHub Actions Community Forum.

FAQs

What images are available for GitHub Actions and Azure DevOps?

The availability of images for GitHub Actions and Azure DevOps is the same. However, deprecation policies may differ. See documentation for more details:

• GitHub Actions
• Azure DevOps

What image version is used in my build?

Usually, image deployment takes 2-3 days, and documentation in the main branch is only updated when deployment is finished. To find out which image version and what software versions are used in a specific build, see Set up job (GitHub Actions) or Initialize job (Azure DevOps) step log.

Looking for other Linux distributions?

We do not plan to offer other Linux distributions. We recommend using Docker if you'd like to build using other distributions with the hosted runner images. Alternatively, you can leverage [self-hosted runners] and fully customize your VM image to your needs.

How does GitHub determine what tools are installed on the images?

For some tools, we always install the latest at the time of the deployment; for others, we pin the tool to specific version(s). For more details please see the Preinstallation Policy

How do I request that a new tool be pre-installed on the image?

Please create an issue and get an approval from us to add this tool to the image before creating the pull request.

What branch should I use to build custom image?

We strongly encourage customers to build their own images using the main branch. This repository contains multiple branches and releases that serve as document milestones to reflect what software is installed in the images at certain point of time. Current builds are not idempotent and if one tries to build a runner image using the specific tag it is not guaranteed that the build will succeed.