Skip to content

Runner 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 runner agent will automatically get installed there.

This feature brings the following benefits:

  • Flexibility: Bringing your own images allows for customization to meet specific project requirements.
  • Compatibility: Ensures that you can easily go back to official GitHub runners should you choose to.
  • Control: Full control over the operating environment of your runners.
  • Security: Use your secure, compliant, and up-to-date images.
  • Efficiency: Optimize the images for faster startup times and better performance.

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.

To use them, simply specificy the image=IMAGE label in your runs-on: definition:

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

For x86_64, use ubuntu22-full-x64 to maintain full compatibility with the GitHub Actions ecosystem:

.github/workflows/my-workflow.yml
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 architecture
runs-on: runs-on,runner=4cpu-linux-x64

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

.github/workflows/my-workflow.yml
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 architecture
runs-on: runs-on,runner=4cpu-linux-arm64

Some more bare-bone images are also available, which are just the bare ubuntu22 image with the runner agent installed. Only use them if you know what you are doing, as most actions won’t work there:

imagedescription
ubuntu22-base-x64base ubuntu22 for x64, with runner agent
ubuntu22-base-arm64base ubuntu22 for arm64, with runner agent

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 "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