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:

image	description
`ubuntu22-full-x64`	x64 image compatible with official GitHub runner image
`ubuntu22-base-x64`	base ubuntu22 for x64, with runner agent
`ubuntu22-full-arm64`	arm64 image with lots of preinstalled software
`ubuntu22-base-arm64`	base 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 ↗.

job: Test
  runs-on: runs-on,runner=4cpu-linux-x64,image=ubuntu22-full-x64
  # can also be abbreviated since this is the default image for that runner
  runs-on: runs-on,runner=4cpu-linux-x64

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

job: Test
  runs-on: runs-on,runner=4cpu-linux-arm64,image=ubuntu22-full-arm64
  # can also be abbreviated since this is the default image for that runner
  runs-on: runs-on,runner=4cpu-linux-arm64

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.

images:
  mycustomimage:
    platform: "linux"
    arch: "x64"
    owner: "099720109477" # Official Ubuntu owner
    name: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*" # Official Ubuntu image

  otherimage:
    platform: "linux"
    arch: "arm64"
    ami: "ami-0abcd159cbfafefgh"

  official_image_with_preinstall:
    platform: "linux"
    arch: "x64"
    owner: "135269210855" # RunsOn owner
    name: "runs-on-v2.2-ubuntu22-full-x64-*" # RunsOn x64 most recent image
    # Assuming you have specified a custom policy (`EC2InstanceCustomPolicy`)
    # so that the runner VMs are able to transparently access ECR
    preinstall: |
      #!/bin/bash
      echo "Doing custom things before job starts"
      su - runner "aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com"

You can then reference them in your workflows:

job: Test
  runs-on: runs-on,runner=2cpu-linux-x64,image=mycustomimage

Or:

job: Test
  runs-on: runs-on,runner=2cpu-linux-arm64,image=otherimage