Custom images

RunsOn provides Linux 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.

Using a custom AMI for your runners

Using a special configuration 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:
  custom_x64_image:
    platform: "linux"
    arch: "x64"
    owner: "099720109477" # Official Ubuntu owner
    name: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*" # Official Ubuntu image

  custom_arm64_image:
    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: |
      echo "Logging into an ECR registry before the 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=custom_x64_image]
  # or
  runs-on: [runs-on,runner=2cpu-linux-arm64,image=custom_arm64_image]
  # or
  runs-on: [runs-on,runner=2cpu-linux-x64,image=official_image_with_preinstall]

Configuration options

Please refer to the Repository configuration section for more details about the configuration file.