Skip to content

Repository configuration

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

If no repository-local configuration file is found (and only in that case), RunsOn will attempt to fetch a global configuration file from your organization’s .github-private repository.

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.
ram: [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 the configuration in a 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 configuration 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