GitHub Actions Runner Images

Table of Contents

• About
• Available Images
• Announcements
• Image Definitions
• 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 Microsoft-hosted agents used for Azure Pipelines. To build a VM machine from this repo's source, see the instructions.

Available Images

Image	YAML Label	Included Software	Rollout Progress of Latest Image Release
Ubuntu 22.04	ubuntu-latest or ubuntu-22.04	ubuntu-22.04
Ubuntu 20.04	ubuntu-20.04	ubuntu-20.04
macOS 13 [beta]	macos-13 or macos-13-xl	macOS-13
macOS 12	macos-latest, macos-latest-xl, macos-12, or macos-12-xl	macOS-12
macOS 11	macos-11	macOS-11
Windows Server 2022	windows-latest or windows-2022	windows-2022
Windows Server 2019	windows-2019	windows-2019

Label scheme

• In general the -latest label is used for the latest OS image version that is GA
• Before moving the-latest label to a new OS version we will announce the change and give sufficient lead time for users to update their workflows

Announcements

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

Image Definitions

Beta

The purpose of a Beta is to collect feedback on an image before it is released to GA. The goal of a Beta is to identify and fix any potential issues that exist on that image. Images are updated on a weekly cadence. Any workflows that run on a beta image do not fall under the customer SLA in place for Actions. Customers choosing to use Beta images are encouraged to provide feedback in the runner-images repo by creating an issue. A Beta may take on different availability, i.e. public vs private.

GA

A GA (General Availability) image has been through a Beta period and is deemed ready for general use. Images are updated on a weekly cadence. In order to be moved to GA the image must meet the following criteria:

1. Has been through a Beta period (public or private)
2. Most major software we install on the image has a compatible version for the underlying OS and
3. All major bugs reported during the Beta period have been addressed.

This image type falls under the customer SLA for actions. GA images are eventually deprecated according to our guidelines as we only support the latest 2 versions of an OS.

Latest Migration Process

GitHub Actions and Azure DevOps use the -latest YAML label (ex: ubuntu-latest, windows-latest, and macos-latest). These labels point towards the newest stable OS version available.

The -latest migration process is gradual and happens over 1-2 months in order to allow customers to adapt their workflows to the newest OS version. During this process, any workflow using the -latest label, may see changes in the OS version in their workflows or pipelines. To avoid unwanted migration, users can specify a specific OS version in the yaml file (ex: macos-12, windows-2022, ubuntu-22.04).

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 twitter.

   • 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:

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.

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