Custom images

RunsOn provides x64 and arm64 images that are fully compatible with official GitHub Actions runners. This makes the transition from GitHub Actions to RunsOn (or the reverse) as easy as changing one line in your workflows.

If you have specific needs, you can also bring your own custom images, by referencing your own AMIs, and RunsOn will boot the runner using that image. The latest version of the GitHub Actions runner agent will automatically get installed there.

Default runner images

RunsOn maintains a set of images that are fully compatible with the official GitHub Actions runners. These images are refreshed every 15 days ↗ from the upstream official GitHub repository ↗.

For reference, here is the list of the default image names, which are automatically selected when referencing a default runner name in your workflow:

image	description
ubuntu22-full-x64	x64 image compatible with official GitHub runner image
ubuntu22-full-arm64	arm64 image with a subset of the same software as the x64 image (until GitHub publishes a reference image for arm64)
ubuntu24-full-x64	x64 image compatible with official GitHub runner image
ubuntu24-full-arm64	arm64 image with a subset of the same software as the x64 image (until GitHub publishes a reference image for arm64)

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" # 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 -c "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:

.github/workflows/my-workflow.yml

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

Or:

.github/workflows/my-workflow.yml

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

More details about the configuration file can be found in the Repository configuration section.

platform

Can either be linux or windows.

arch

Can either be x64 or arm64.

owner

Must be the AWS account ID of the owner of the AMI.

name

Full or partial AMI name, with wildcards. Optional if ami is specified.

ami

AMI ID. Optional if name is specified.

tags

A list of key-value tags used to filter the images.

.github/runs-on.yml

images:
  custom:
    owner: "123456789"
    name: "my-org/my-image-name-*"
    arch: x64
    platform: linux
    tags:
      # filter with specific value
      is-production-ready: "true"
      # allow any value
      other-tag: "*"

preinstall

A preinstall script that will be executed on the runner before the job starts. Mainly useful to perform pre-authentication steps, such as logging into private registries. Installing additional software will make your runner boot time slower, it is recommended that you create your own AMI instead.

If the preinstall script fails, the job will fail. You will find the preinstall exit status and logs in the “Set up runner” section of the job logs.

Platform behaviour:

• On Linux, the preinstall script is executed as the root user, before the GitHub Actions runner agent is launched. The script must be a valid bash script, and will be executed with bash -e (so any failure will fail the script immediately). See the official_image_with_preinstall custom image in the code sample above for an example.

• This option is not yet available for Windows images.