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:

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)

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

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:

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:

image	description
`ubuntu22-base-x64`	base ubuntu22 for x64, with runner agent
`ubuntu22-base-arm64`	base 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.

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]