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.

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.

Structure

The configuration file is a YAML file with the following structure:

.github/runs-on.yml

_extends: ...
runners: {...}
images: {...}
admins: [...string]

_extends

If set, the configuration file will inherit from the configuration file in the repository specified by the _extends value.

A common use case is to define a global configuration file in the .github-private repository of your organization, and then inherit from it in other repositories. Do not forget to allow the RunsOn GitHub App to access the repository hosting the global configuration file.

Example:

.github/runs-on.yml

_extends: .github-private

runners:
  ...

In this example, the configuration file in the repository will inherit from the configuration file stored at .github/runs-on.yml in the .github-private repository.

runners

Mapping of runner names to runner configuration.

Configuration options available are the same as the job-level labels, but with the additional preinstall option available (see example below):

• cpu: array of integers.
• ram: array of integers.
• disk: string.
• family: array of strings.
• spot: boolean or string.
• image: string.
• ssh: boolean.
• extras: array of strings.
• private: boolean.
• retry: string.
• preinstall: string. Script to run on the runner, before the GitHub Actions runner agent is executed.

Example:

.github/runs-on.yml

runners:
  docker-ipv6:
    cpu: [2, 4]
    ram: [2, 4, 8]
    disk: default
    family: ["c7", "m7", "r7"]
    spot: capacity-optimized
    preinstall: |
      cat > /etc/docker/daemon.json <<EOF
      {
        "ipv6": true,
        "fixed-cidr-v6": "2001:db8:1::/64"
      }
      EOF
      systemctl restart docker
  other-runner:
    ...

And the runner will be available for use in the repository:

jobs:
  test:
    runs-on: runs-on=${{ github.run_id }}/runner=docker-ipv6

images

Mapping of image names to image configuration.

Available configuration options:

• name: string. Can include wildcards, in which case RunsOn will pick the most recent image matching the pattern.
• ami: string. If set, the image will be pinned to the specified AMI, irrespective of the name option.
• platform: string.
• arch: string.
• owner: string.
• preinstall: string. Script to run on the runner, before the GitHub Actions runner agent is executed. Takes precedence over the preinstall option at the runner level if both are set.
• tags: mapping of key-value tags to filter the image when searching for it.

.github/runs-on.yml

images:
  custom:
    owner: "123456789"
    name: "my-org/my-image-name-*"
    arch: x64
    platform: linux
    tags:
      # filter with specific value
      is-production-ready: "true"
      # allow any value
      other-tag: "*"

  fixed-ami:
    ami: "ami-0abcd159cbfafefgh"

And you can use the image in your workflows like this:

jobs:
  test:
    runs-on: runs-on=${{ github.run_id }}/image=custom
    # or
    runs-on: runs-on=${{ github.run_id }}/image=fixed-ami

admins

List of GitHub usernames that have SSH access to the runners launched for this repository. They come in addition to the admins defined at the CloudFormation stack level.

Example:

.github/runs-on.yml

admins:
  - crohr
  - other-github-user

Full example

.github/runs-on.yml

_extends: .github-private

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
    disk: large
    family: ["c7a", "m7a"]
    spot: false
    # reference custom image defined above
    image: mycustomimage
    preinstall: |
      echo "doing some stuff before the GitHub Actions runner agent is executed..."

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