Skip to content

Configuration file

RunsOn supports describing various options through a configuration file. This file is located at .github/runs-on.yml in the repository where you are using RunsOn runners.

The configuration file supports defining:

  • custom images
  • custom runners
  • the list of admins having SSH access to the runners

Example

.github/runs-on.yml
images:
mycustomimage:
platform: "linux"
arch: "x64"
owner: "099720109477"
# will take the most recent AMI matching the wildcard pattern
name: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"
otherimage:
platform: "linux"
arch: "x64"
ami: "ami-0abcd159cbfafefgh"
runners:
cheap:
# Useful for workflows that do not require a lot of CPU / RAM.
# RunsOn will automatically choose the instance with the lowest CPU count among the matching instances.
cpu: [1, 2]
ram: [1, 2, 4, 8]
# Burstable instances, valid for both x64 and arm64
family: ["t3", "t4"]
image: otherimage
ssh: false
fast:
cpu: 32
# Increase disk size to 80GB
hdd: 80
family: ["c7a", "m7a"]
spot: false
image: ubuntu22-full-x64
admins:
- crohr
- other-github-user

Using it in GitHub Workflow

.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,runner=2cpu-linux-x64,image=mycustomimage
.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,runner=2cpu-linux-x64,image=otherimage
.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,runner=cheap
.github/workflows/my-workflow.yml
job: Test
runs-on: runs-on,runner=fast

Sharing configuration across repositories

RunsOn comes with a feature that allows a local configuration file to inherit from a globally defined configuration file, by using the _extends directive.

The recommendation is to store the global cofniguration file in the special .github-private repository of your organization, but you can choose any other repository as well (public or private).

Example:

your-repo/.github/runs-on.yml
_extends: .github-private
.github-private/.github/runs-on.yml
runners:
cheap-arm64:
cpu: [1, 2]
family: ["t4g"]
image: ubuntu22-full-arm64