Runner types
RunsOn supports flexible runner configuration, allowing you to set your runner’s CPU, RAM, instance type FAMILY and HDD size at runtime, depending on your workflow requirements. This flexibility allows you to optimize your runners for each job, and ensure you do not pay for unused resources.
It is also very useful if you ever find yourself splitting tests in many different jobs, because with RunsOn you now have access to far larger runners, up to hundreds of CPUs if you like! So stop wasting engineering resources going around your CI provider self-imposed constraints, and just ask for a far beefier runner than what GitHub provides (AWS instances have also faster CPUs than GitHub Actions runners).
Flexible runner selection at runtime
The way you can define your requirements is by specifying custom labels on in your runs-on:
definition. Or, you can define a custom runner type in a .github/runs-on.yml
configuration file in your repository, and reference that custom runner with the runner=RUNNER
label.
For instance, if you want a runner with 4+ CPUs, 16GB+ RAM, in the instance type family of either m7a
or m7i-flex
, and with a disk size of 80GB:
job: Test runs-on: [runs-on,cpu=4,ram=16,family=m7a+m7i-flex,hdd=80,image=ubuntu22-full-x64]
Sometimes you might also find this alternative syntax useful:
job: Test runs-on: - runs-on - cpu=4 - ram=16 - family=m7a+m7i-flex - hdd=80 - image=ubuntu22-full-x64
If you specify multiple values for family
, AWS will start the instance that matches the requirements, and is ranked best according to the selected spot
allocation strategy, at the time of launch. Sometimes it can happen that a beefier instance is cheaper than a smaller one on the spot marklet.
Available runs-on:
labels
cpu
Number of vCPUs to request (default: 2
). If you set multiple values, RunsOn will request any instance matching the lowest up to the highest value.
E.g.
cpu=4
will ensure that the runner has 4 vCPUs (min=4, max=4).cpu=4+16
will ensure that the runner has at least 4 vCPUs but also consider instances with up to 16 vCPUs.
Setting a variable amount of vCPUs is useful for expanding the pool of available spot instances, if your workflow is not to sensitive to the exact number of vCPUs.
ram
Amount of memory to request, in GB (default: 0
). If you set multiple values, RunsOn will request any instance matching the lowest up to the highest value.
E.g.
ram=16
will ensure that the runner has 16GB of RAM (min=16, max=16).ram=16+64
will ensure that the runner has at least 16GB of RAM but also consider instances with up to 64GB of RAM.
family
Instance type family. Can either be the full name (family=c7a.large), or a partial name (family=c7). Can accept multiple values (family=c7+c6).
E.g. family=c7a+c6
will ensure that the runner has at least one instance type in the c7a*
or c6*
instance type family.
image
Runner image to use (see Runner images).
E.g. image=ubuntu22-full-x64
will ensure that the runner is launched with the ubuntu22-full-x64
image.
hdd
Disk size, in GB (default: 40
).
Since v2.2 this label is a bit misleading, because you can actually only get one of 2 disk configurations, which are configured in the CloudFormation template (by default, small runner has 40GB, large runner has 80GB).
For instance, if you set hdd=41
and your small runner is specified to use 40GB, the runner will be launched with the large runner configuration.
The disk size and volume throughput for each runner size can be configured when you install or update RunsOn.
spot
Whether to attempt to use spot pricing (default: true
, equivalent to price-capacity-optimized
). Can be set to an explicit spot allocation strategy.
E.g. spot=false
will ensure that the runner is launched with regular on-demand pricing.
Supported allocation strategies on RunsOn include:
spot=price-capacity-optimized
orspot=pco
: This strategy balances between price and capacity to optimize cost while minimizing the risk of interruption.spot=lowest-price
orspot=lp
: This strategy focuses on obtaining the lowest possible price, which may increase the risk of interruption.spot=capacity-optimized
orspot=co
: This strategy prioritizes the allocation of instances from the pools with the most available capacity, reducing the likelihood of interruption.
For more details on each strategy, refer to the official AWS documentation on Spot Instance allocation strategies ↗.
ssh
Whether to enable SSH access (default: true
).
E.g. ssh=false
will ensure that the runner is launched with SSH access fully disabled.
runner
Using the previous labels, you can configure every aspect of a runner right from the runs-on:
workflow job definition.
However, if you want to reuse a runner configuration across multiple workflows, you can define a custom runner type in a .github/runs-on.yml
configuration file in the repository where you want those runners to be available, and reference that runner type with the runner
label.
E.g. runner=16cpu-linux-x64
will ensure that the runner is launched with the 16cpu-linux-x64
runner type. See below to learn more about default and custom runner configurations using the runner
label 👇.
Default runners types
RunsOn comes with the following preconfigured runner types, for both x64
and arm64
architectures:
Runner | RunsOn | GitHub | RunsOn vs GitHub |
---|---|---|---|
1cpu-linux-x64 | $0.0008 | - | - |
2cpu-linux-x64 | $0.0011 | $0.0080 | 7.2x cheaper |
4cpu-linux-x64 | $0.0019 | $0.0160 | 8.6x cheaper |
8cpu-linux-x64 | $0.0034 | $0.0320 | 9.5x cheaper |
16cpu-linux-x64 | $0.0068 | $0.0640 | 9.4x cheaper |
32cpu-linux-x64 | $0.0114 | $0.1280 | 11.3x cheaper |
48cpu-linux-x64 | $0.0165 | - | - |
64cpu-linux-x64 | $0.0147 | $0.2560 | 17.4x cheaper |
Runner | RunsOn | GitHub | RunsOn vs GitHub |
---|---|---|---|
1cpu-linux-arm64 | $0.0006 | - | - |
2cpu-linux-arm64 | $0.0010 | $0.0050 | 5.1x cheaper |
4cpu-linux-arm64 | $0.0014 | $0.0100 | 7.3x cheaper |
8cpu-linux-arm64 | $0.0029 | $0.0200 | 7.0x cheaper |
16cpu-linux-arm64 | $0.0048 | $0.0400 | 8.4x cheaper |
32cpu-linux-arm64 | $0.0098 | $0.0800 | 8.2x cheaper |
48cpu-linux-arm64 | $0.0141 | - | - |
64cpu-linux-arm64 | $0.0200 | $0.1600 | 8.0x cheaper |
$/min, us-east-1 prices. Includes compute + storage costs
for the most recent EC2 family types (m7a*
,m7i*
, m7g*
).
Savings are even higher if you include the speed gains or switch
to previous-generation instance types.
An example runs-on
definition for a 16CPU x64 runner would then be:
job: Test runs-on: [runs-on,runner=16cpu-linux-x64]
Custom runner types
Default runners are fine for standard workflows, but sometimes you may need custom runner types. In that case, you can define your own custom runner types using the special .github/runs-on.yml
configuration file in the repository where you want those new runners to be available:
runners: cheap: ram: [4, 16] family: ["t3"] image: ubuntu22-full-x64 ssh: false fast: cpu: [32, 64] hdd: 80 family: ["c7a", "m7a"] image: ubuntu22-full-x64 spot: false
And then in your workflows:
runs-on: [runs-on,runner=fast]
Custom runner types allow redefining a preinstall
step, which can contain instructions to install additional software on the runner, right before the GitHub runner agent is launched:
runners: with-preinstall: ram: 4 family: ["t3"] image: ubuntu22-full-x64 preinstall: | echo "Hello from preinstall" ssh: false
And then in your workflows:
job: Test runs-on: [runs-on,runner=with-preinstall]
The preinstall output (stdout + stderr) will be displayed in the “Set up runner” step of the workflow. If it exits with a non-zero code, the job will be aborted.
![Failed preinstall step](/_astro/2149e58c-536f-4ded-9d40-e04fb2f6beca_1iNV8Y.webp)
Note that a preinstall
defined at the runner
level will override any preinstall
defined at the runner image level.