runs-on: label

The label you assign to your runs-on: directive in your GitHub Actions workflow yml lets you directly control where your jobs run, on what instance type they run, what image they use and how much temp storage they get.

For Sprinters at the bare minimum it looks like this:

runs-on: sprinters:aws/ubuntu-latest

The label in the example above tells Sprinters to run your job on AWS using the ubuntu-latest image. This image is identical to the one provided by GitHub.

A number of defaults will also be applied automatically to most closely matches the capacity of GitHub hosted runners:

• The instance will be a t3.2xlarge (x64 with 2 vCPUs).
• It will have 14 GiB of temp disk space and 4 GiB of swap.

The instance placement will be as follows:

• It will be launched in the us-east-1 region in your account’s default VPC.
• Sprinters will automatically pick the availability zone that currently has the lowest spot price.
• Sprinters will attempt to launch the instance as spot and automatically fall back to on-demand if AWS has insufficient spot capacity available.

Customization

This specification can be customized by adding various parts to the label. The order doesn’t matter. All parts are separated by a /.

Here is a more complex example:

runs-on: sprinters:aws/ubuntu-22.04/eu-central-1/m7i.24xlarge/temp=64

This will launch a runner using the ubuntu-22.04 image in the eu-central-1 region on a m7i.24xlarge instance with 64 GiB of temp space.

The following label parts can be added or modified to customize the placement and capacity of the instance:

• Image
• AWS Region
• AWS Availability Zone
• AWS VPC / Subnet ID
• AWS Instance Type
• AWS Spot Instances
• Temp Disk Space
• Swap Disk Space

Image

You can set the image for the runner by replacing the one in the label.

Format: image-name
Default: ubuntu-latest

Supported Image Types

Example

To set the image to minimal, change the label to:

runs-on: sprinters:aws/minimal

AWS Region

You can set the AWS region where to launch the runner by appending it to the label.

Format: aws-region
Default: us-east-1

Supported Regions

• eu-central-1
• us-east-1

More regions will be added soon. To request support for a specific region, file an issue in the issue tracker.

Notes

• If you specify both a region and an availability zone, you must ensure the availability zone resides in that region.
• If you specify both a region and a subnet id, you must ensure the subnet resides in that region.

Example

To set the region to eu-central-1 and run using the minimal image, change the label to:

runs-on: sprinters:aws/minimal/eu-central-1

AWS Availability Zone

Within an AWS region, you can pick the availability of your choice where to launch the runner by appending the availability zone to the label.

Format: aws-availability-zone
Default: availability zone of the selected region that currently has the lowest spot price for the selected instance type

Notes

• If you don’t specify a region, Sprinters will automatically select the matching region for the availability zone.
• If you specify both an availability zone and a region, you must ensure the availability zone resides in that region.
• If you specify both an availability zone and a subnet id, you must ensure the subnet resides in that availability zone.

Example

To use the eu-central-1c availability zone, change the label to:

runs-on: sprinters:aws/ubuntu-latest/eu-central-1c

AWS VPC / Subnet ID

Within an AWS region, you can pick the subnet in the VPC of your choice where to launch the runner by appending the subnet ID to the label.

Format: aws-subnet-id
Default: default subnet of the default VPC in the selected availability zone of the selected region

Notes

• If you specify both a subnet id and a region, you must ensure the subnet resides in that region.
• If you specify both a subnet id and an availability zone, you must ensure the subnet resides in that availability zone.

Example

To use the subnet-0123456789abcdef0 subnet, change the label to:

runs-on: sprinters:aws/ubuntu-latest/subnet-0123456789abcdef0

AWS Instance Type

You can set the AWS EC2 instance type on which launch the runner by appending it to the label.

Format: aws-instance-type
Default: t3.2xlarge

Supported Instance Types

More instance families will be added soon. To request support for a specific instance family, file an issue in the issue tracker.

Example

To set the instance type to m7i.8xlarge, change the label to:

runs-on: sprinters:aws/ubuntu-latest/m7i.8xlarge

AWS Spot Instances

To save significant amounts of money at a slight risk of being interrupted, the instance can be launched as a spot instance.

Format: spot=auto|true|false
Default: auto

Supported Modes

Note

If neither a subnet id nor an availability zone was specified, Sprinters will automatically select the availability zone with the cheapest spot price.

Example

To use a much cheaper spot instance, change the label to:

runs-on: sprinters:aws/ubuntu-latest/spot=true

Temp Disk Space

You can set the temp disk space available for the runner from 1 GiB to 16384 GiB by appending it to the label.

Format: temp=size-in-gib
Default: 14

Example

To set the temp disk space to 512 GiB, change the label to:

runs-on: sprinters:aws/ubuntu-latest/temp=512

Swap Disk Space

You can set the swap size for the runner from 1 GiB to 16384 GiB by appending it to the label.

Format: swap=size-in-gib
Default: 4

Example

To set the swap size to 64 GiB, change the label to:

runs-on: sprinters:aws/ubuntu-latest/swap=64