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
|x64 image compatible with official GitHub runner image
|base ubuntu22 for x64, with runner agent
|arm64 image with lots of preinstalled software
|base ubuntu22 for arm64, with runner agent
For ARM64, use
ubuntu22-full-arm64 to maintain compatibility with most of the GitHub Action ecosystem.
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 (
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.
You can then reference them in your workflows: