Configuring RunsOn Runners

Customize CPU, RAM, instance types, and images for your workflows

RunsOn provides flexible configuration through job labels, repository configuration files, and stack-level settings. This guide covers all configuration options.

Job label syntax#

The simplest way to configure runners is through the runs-on label in your workflow:

1
runs-on: runs-on=${{ github.run_id }}/runner=<runner-type>

The ${{ github.run_id }} ensures each workflow run gets unique runner instances.

Pre-defined runner types#

RunsOn provides pre-configured runner types for common use cases:

Linux x64#

Linux ARM64#

Prices shown are for spot instances. On-demand pricing is approximately 3x higher.

Custom configuration#

For fine-grained control, use individual parameters in the label:

1
runs-on: runs-on=${{ github.run_id }}/cpu=4/ram=16/family=m7a+m7i-flex

Available parameters#

Examples#

High-memory build:

1
runs-on: runs-on=${{ github.run_id }}/cpu=8/ram=64/family=r7i

Large disk for artifacts:

1
runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64/volume=200

On-demand for critical jobs:

1
runs-on: runs-on=${{ github.run_id }}/runner=8cpu-linux-x64/spot=false

ARM64 with custom image:

1
runs-on: runs-on=${{ github.run_id }}/cpu=4/family=m7g/image=ubuntu24-full-arm64

Default images#

RunsOn provides four pre-built Ubuntu images that mirror GitHub-hosted runner tooling:

Images are rebuilt every 15 days from the official GitHub runner-images repository to maintain compatibility.

Custom images#

Create custom AMIs with pre-installed dependencies for faster job startup:

1. Launch an instance with a base RunsOn image
2. Install your custom software and dependencies
3. Create an AMI from the instance
4. Reference the AMI in your workflow:

1
runs-on: runs-on=${{ github.run_id }}/image=ami-0123456789abcdef0

For wildcard-based automatic updates, name your AMIs with a pattern:

1
runs-on: runs-on=${{ github.run_id }}/image=my-custom-image-*

RunsOn automatically uses the latest AMI matching the pattern.

Repository configuration#

Create a .github/runs-on.yml file for repository-level defaults:

1
# .github/runs-on.yml
2
defaults:
3
  runner: 4cpu-linux-x64
4
  spot: true
5
6
images:
7
  my-image:
8
    ami: ami-0123456789abcdef0
9
10
runners:
11
  large-build:
12
    cpu: 16
13
    ram: 64
14
    family: c7i

Reference custom runners in workflows:

1
runs-on: runs-on=${{ github.run_id }}/runner=large-build

Stack configuration#

Configure organization-wide defaults via CloudFormation parameters:

Instance families#

Choose instance families based on workload characteristics:

Combine families with + for flexibility:

1
runs-on: runs-on=${{ github.run_id }}/cpu=4/family=m7i+m7a+c7i

RunsOn selects the most cost-effective available instance.

Spot instances#

Spot instances provide 60-90% cost savings. RunsOn handles spot interruptions automatically:

• Jobs are retried on a new instance if interrupted
• On-demand fallback available for critical jobs
• Interruption rate is typically under 5%

Disable spot for time-sensitive jobs:

1
runs-on: runs-on=${{ github.run_id }}/runner=8cpu-linux-x64/spot=false

Resource tagging#

Add AWS tags for cost allocation:

1
runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64/tag:team=platform/tag:project=api

Tags appear on EC2 instances and related resources for cost tracking.

Next steps#

• Set up caching to accelerate builds
• Review Linux runner options for detailed specifications
• Explore GPU runners for ML workloads