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

Note

On public repositories, RunsOn only reads the configuration file from the repository default branch. If you update the configuration file in a branch, the new settings will not be applied until the branch is merged into the default branch.

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]

Note

Make sure your runner and image definitions are compatible, i.e. you cannot mix runner types that target x64 architecture (e.g. c7a), with an image targetting arm64 architecture (e.g. ubuntu22-full-arm64).

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).

Note

Make sure that the RunsOn GitHub App has access to the repository hosting the global configuration. Inherited configuration is always pulled from the inherited repository’s default branch.

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