Skip to content

Runner images

Runner instances boot from an Amazon AMI. By default we recommend Ubuntu 22 as the distribution for your AMIs, but any Linux variant (including Amazon Linux 2) should work.

Larger AMIs will take more time to boot: AMI snapshot must be restored from S3, so larger AMI means more blocks to fetch.

Default runner images

RunsOn allows to define the base image to be used for each workflow. Sometimes you’ll want the full image, sometimes a small one, and sometimes a custom one. The smaller the image, the faster the runner will boot.

RunsOn comes with a few predefined image types, that you can use in your workflow by assigning the image label to the runs-on definition:

imagedescription
ubuntu22-full-x64x64 image compatible with official GitHub runner image
ubuntu22-base-x64base ubuntu22 for x64, with runner agent
ubuntu22-full-arm64arm64 image with lots of preinstalled software
ubuntu22-base-arm64base ubuntu22 for arm64, with runner agent

If you want the same runner image as what is provided by GitHub, use ubuntu22-full-x64. Those are refreshed by runs-on/runner-images-for-aws 🔗 every time a new image version is pushed by GitHub 🔗.

.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,image=ubuntu22-full-x64,runner=4cpu-linux

For ARM64, use ubuntu22-full-arm64 to maintain compatibility with most of the GitHub Action ecosystem.

.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,image=ubuntu22-full-arm64,runner=4cpu-linux

All the other images are variants of the bare ubuntu22 official image as provided by canonical. The only additional thing installed is the runner binary. The runner user has full sudo access if you want to install more things.

Custom runner images

You can also define your own custom images, by using a special config file (.github/runs-on.yml) in your repository. You can either:

  • reference a specific AMI (make sure it is available in the region where you have deployed RunsOn)

  • reference by name, owner, platform, architecture (x64 or arm64). The name can include a wildcard. In that case, RunsOn will query the EC2 API to find the most recent image matching the name. This is a good way to ensure your workflows always take the latest AMI available, for instance if you regularly update a base custom AMI nightly.

.github/runs-on.yml
images:
mycustomimage:
platform: "linux"
arch: "x64"
owner: "099720109477"
name: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"
otherimage:
platform: "linux"
arch: "x64"
ami: "ami-0abcd159cbfafefgh"

You can then reference them in your workflows:

.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,image=mycustomimage

Or:

.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,image=otherimage