GitHub uses the runs-on: label in your workflow yml to determine which runner to use for a job.
Migrating from GitHub-hosted runners to Sprinters-powered runners on AWS is easy.
All you need to do, is locate the runs-on: label in your workflow yml:
runs-on: ubuntu-latest
And adjust it to:
runs-on: sprinters:aws:ubuntu-latest
Now, whenever this job is started, Sprinters will automatically launch a runner for it on your AWS account as
a t3.large (x64, 2 vCPUs, 8 GiB RAM) EC2 instance with 14 GiB of temp disk space and 4 GiB of swap
in the default VPC of the us-east-1 region using the ubuntu-latest image.
This default most closely matches GitHub-hosted runners, at a fraction of the price.
You can adjust the image, the AWS account, the AWS region/az/subnet,
the EC2 instance type, whether to use spot instances,
the performance of the root volume, the performance and size of the temp volume and
whether to use runner lifecycle events
by adding or changing various parts to the label. All parts are separated by a colon (:) and may appear in any order.
For example:
runs-on: sprinters:aws:eu-central-1:ubuntu-22.04:m7i.24xlarge:temp=64
This instructs Sprinters to launch a runner in the eu-central-1 region using the ubuntu-22.04 image on a m7i.24xlarge instance with 64 GiB of temp space.
You can customize the label with the following parts:
You can set the image for the runner by replacing the one in the label.
image-name
ubuntu-latest
| Image | Description |
|---|---|
ubuntu-latest ubuntu-24.04 |
Identical to the one available for GitHub-hosted runners |
ubuntu-24.04-slim |
Identical to the one available for GitHub-hosted runners, minus Android, CodeQL, Haskell and Julia |
ubuntu-24.04-minimal |
Minimal, fast-booting image containing only Git, Git LFS, the GitHub CLI and Docker |
| Image | Description |
|---|---|
ubuntu-22.04 |
Identical to the one available for GitHub-hosted runners |
ubuntu-22.04-slim |
Identical to the one available for GitHub-hosted runners, minus Android, CodeQL, Haskell and Julia |
ubuntu-22.04-minimal |
Minimal, fast-booting image containing only Git, Git LFS, the GitHub CLI and Docker |
| Image | Description |
|---|---|
ubuntu-22.04-arm |
Identical to the one available for GitHub-hosted runners |
ubuntu-22.04-arm-minimal |
Minimal, fast-booting image containing only Git, Git LFS, the GitHub CLI and Docker |
| Image | Description |
|---|---|
ubuntu-22.04-arm |
Identical to the one available for GitHub-hosted runners |
ubuntu-22.04-arm-minimal |
Minimal, fast-booting image containing only Git, Git LFS, the GitHub CLI and Docker |
To set the image to ubuntu-24.04-minimal, change the label to:
runs-on: sprinters:aws:ubuntu-24.04-minimal
You can specify where the runner instance is launched by appending a region, availability zone and subnet id to the label.
At least one of region and availability zone must be specified. subnet id is optional.
All parts are separated by a /.
aws-region/aws-availability-zone/aws-subnet-id
us-east-1 (random subnet of a random availability zone of the default VPC of us-east-1)
| Region | Location |
|---|---|
ap-northeast-1 |
Tokyo |
ap-south-1 |
Mumbai |
ca-central-1 |
Canada |
eu-central-1 |
Frankfurt |
eu-west-1 |
Ireland |
eu-west-2 |
London |
me-central-1 |
UAE |
us-east-1 |
N. Virginia |
us-west-2 |
Oregon |
Need a different region? Simply request it in the issue tracker.
To launch the runner using the ubuntu-24.04-minimal image in the eu-central-1 region, change the label to:
runs-on: sprinters:aws:ubuntu-24.04-minimal:eu-central-1
To use the eu-central-1c availability zone, change the label to:
runs-on: sprinters:aws:ubuntu-latest:eu-central-1c
To use the subnet-0123456789abcdef0 subnet in the us-east-1 region, change the label to:
runs-on: sprinters:aws:us-east-1/subnet-0123456789abcdef0:ubuntu-latest
When using multiple AWS accounts, you can specify the desired account ID in the label.
aws-account-id
The id of your default AWS account.
To launch the runner in your 123456789012 AWS account, change the label to:
runs-on: sprinters:aws/123456789012:ubuntu-latest
You can set the AWS EC2 instance type on which launch the runner by appending it to the label.
aws-instance-type
t3.large for x64 images, t4g.large for arm64 images.
| Family | Sizes |
|---|---|
| c5 | c5.large , c5.xlarge , c5.2xlarge , c5.4xlarge , c5.9xlarge , c5.12xlarge , c5.18xlarge , c5.24xlarge |
| c6i | c6i.large , c6i.xlarge , c6i.2xlarge , c6i.4xlarge , c6i.8xlarge , c6i.12xlarge , c6i.16xlarge , c6i.24xlarge , c6i.32xlarge |
| c7i | c7i.large , c7i.xlarge , c7i.2xlarge , c7i.4xlarge , c7i.8xlarge , c7i.12xlarge , c7i.16xlarge , c7i.24xlarge , c7i.48xlarge |
| c7i-flex | c7i-flex.large , c7i-flex.xlarge , c7i-flex.2xlarge , c7i-flex.4xlarge , c7i-flex.8xlarge , c7i-flex.12xlarge , c7i-flex.16xlarge |
| m5 | m5.large , m5.xlarge , m5.2xlarge , m5.4xlarge , m5.8xlarge , m5.12xlarge , m5.16xlarge , m5.24xlarge |
| m6i | m6i.large , m6i.xlarge , m6i.2xlarge , m6i.4xlarge , m6i.8xlarge , m6i.12xlarge , m6i.16xlarge , m6i.24xlarge , m6i.32xlarge |
| m7i | m7i.large , m7i.xlarge , m7i.2xlarge , m7i.4xlarge , m7i.8xlarge , m7i.12xlarge , m7i.16xlarge , m7i.24xlarge , m7i.48xlarge |
| m7i-flex | m7i-flex.large , m7i-flex.xlarge , m7i-flex.2xlarge , m7i-flex.4xlarge , m7i-flex.8xlarge , m7i-flex.12xlarge , m7i-flex.16xlarge |
| r5 | r5.large , r5.xlarge , r5.2xlarge , r5.4xlarge , r5.8xlarge , r5.12xlarge , r5.16xlarge , r5.24xlarge |
| r6i | r6i.large , r6i.xlarge , r6i.2xlarge , r6i.4xlarge , r6i.8xlarge , r6i.12xlarge , r6i.16xlarge , r6i.24xlarge , r6i.32xlarge |
| r7i | r7i.large , r7i.xlarge , r7i.2xlarge , r7i.4xlarge , r7i.8xlarge , r7i.12xlarge , r7i.16xlarge , r7i.24xlarge , r7i.48xlarge |
r8i.large , r8i.xlarge , r8i.2xlarge , r8i.4xlarge , r8i.8xlarge , r8i.12xlarge , r8i.16xlarge , r8i.24xlarge , r8i.32xlarge , r8i.48xlarge , r8i.96xlarge |
|
r8i-flex.large , r8i-flex.xlarge , r8i-flex.2xlarge , r8i-flex.4xlarge , r8i-flex.8xlarge , r8i-flex.12xlarge , r8i-flex.16xlarge |
|
| t3 | t3.nano , t3.micro , t3.small , t3.medium , t3.large , t3.xlarge , t3.2xlarge |
| Family | Sizes |
|---|---|
| c5a | c5a.large , c5a.xlarge , c5a.2xlarge , c5a.4xlarge , c5a.8xlarge , c5a.12xlarge , c5a.16xlarge , c5a.24xlarge |
| c6a | c6a.large , c6a.xlarge , c6a.2xlarge , c6a.4xlarge , c6a.8xlarge , c6a.12xlarge , c6a.16xlarge , c6a.24xlarge , c6a.32xlarge , c6a.48xlarge |
| c7a | c7a.medium , c7a.large , c7a.xlarge , c7a.2xlarge , c7a.4xlarge , c7a.8xlarge , c7a.12xlarge , c7a.16xlarge , c7a.24xlarge , c7a.32xlarge , c7a.48xlarge |
| m5a | m5a.large , m5a.xlarge , m5a.2xlarge , m5a.4xlarge , m5a.8xlarge , m5a.12xlarge , m5a.16xlarge , m5a.24xlarge |
| m6a | m6a.large , m6a.xlarge , m6a.2xlarge , m6a.4xlarge , m6a.8xlarge , m6a.12xlarge , m6a.16xlarge , m6a.24xlarge , m6a.32xlarge , m6a.48xlarge |
| m7a | m7a.medium , m7a.large , m7a.xlarge , m7a.2xlarge , m7a.4xlarge , m7a.8xlarge , m7a.12xlarge , m7a.16xlarge , m7a.24xlarge , m7a.32xlarge , m7a.48xlarge |
| r5a | r5a.large , r5a.xlarge , r5a.2xlarge , r5a.4xlarge , r5a.8xlarge , r5a.12xlarge , r5a.16xlarge , r5a.24xlarge |
| r6a | r6a.large , r6a.xlarge , r6a.2xlarge , r6a.4xlarge , r6a.8xlarge , r6a.12xlarge , r6a.16xlarge , r6a.24xlarge , r6a.32xlarge , r6a.48xlarge |
| r7a | r7a.medium , r7a.large , r7a.xlarge , r7a.2xlarge , r7a.4xlarge , r7a.8xlarge , r7a.12xlarge , r7a.16xlarge , r7a.24xlarge , r7a.32xlarge , r7a.48xlarge |
| t3a | t3a.nano , t3a.micro , t3a.small , t3a.medium , t3a.large , t3a.xlarge , t3a.2xlarge |
| Family | Sizes |
|---|---|
| c6g | c6g.medium , c6g.large , c6g.xlarge , c6g.2xlarge , c6g.4xlarge , c6g.8xlarge , c6g.12xlarge , c6g.16xlarge |
| c7g | c7g.medium , c7g.large , c7g.xlarge , c7g.2xlarge , c7g.4xlarge , c7g.8xlarge , c7g.12xlarge , c7g.16xlarge |
| c8g | c8g.medium , c8g.large , c8g.xlarge , c8g.2xlarge , c8g.4xlarge , c8g.8xlarge , c8g.12xlarge , c8g.16xlarge , c8g.24xlarge , c8g.48xlarge |
| m6g | m6g.medium , m6g.large , m6g.xlarge , m6g.2xlarge , m6g.4xlarge , m6g.8xlarge , m6g.12xlarge , m6g.16xlarge |
| m7g | m7g.medium , m7g.large , m7g.xlarge , m7g.2xlarge , m7g.4xlarge , m7g.8xlarge , m7g.12xlarge , m7g.16xlarge |
| m8g | m8g.medium , m8g.large , m8g.xlarge , m8g.2xlarge , m8g.4xlarge , m8g.8xlarge , m8g.12xlarge , m8g.16xlarge , m8g.24xlarge , m8g.48xlarge |
| r6g | r6g.medium , r6g.large , r6g.xlarge , r6g.2xlarge , r6g.4xlarge , r6g.8xlarge , r6g.12xlarge , r6g.16xlarge |
| r7g | r7g.medium , r7g.large , r7g.xlarge , r7g.2xlarge , r7g.4xlarge , r7g.8xlarge , r7g.12xlarge , r7g.16xlarge |
| r8g | r8g.medium , r8g.large , r8g.xlarge , r8g.2xlarge , r8g.4xlarge , r8g.8xlarge , r8g.12xlarge , r8g.16xlarge , r8g.24xlarge , r8g.48xlarge |
| t4g | t4g.nano , t4g.micro , t4g.small , t4g.medium , t4g.large , t4g.xlarge , t4g.2xlarge |
Need a different instance family? Simply request it in the issue tracker.
To set the instance type to m7i.8xlarge, change the label to:
runs-on: sprinters:aws:ubuntu-latest:m7i.8xlarge
To save significant amounts of money at a slight risk of being interrupted, the instance can be launched as a spot instance.
spot=auto|true|false
false
| Mode | Description |
|---|---|
auto |
Attempt to launch the instance as spot. Automatically fall back to on-demand if AWS currently doesn’t have enough spot capacity available. This guarantees that a job will be able to run and most of the time it will do so saving significant amounts of money using a spot instance. |
true |
Force the instance to launch as spot. Fail if AWS currently doesn’t have enough spot capacity available. |
false |
Always run as on-demand, foregoing the savings of spot for guaranteed execution. |
If neither a subnet id nor an availability zone was specified, Sprinters will automatically select the availability zone with the cheapest spot price.
To force the use of much cheaper spot instances, change the label to:
runs-on: sprinters:aws:ubuntu-latest:spot=true
You can adjust the performance of the root volume by appending a performance specification to the label.
root=volume-type/iops/throughput
gp3 volume with 3000 IOPS and 150 MiB/s throughput.
Only gp3 volumes are supported for now.
Between 3000 and 16000 IOPS are supported, depending on the size of the volume.
Use max for the maximum number of IOPS for the current volume size.
Between 125 and 1000 MiB/s are supported, depending on the number of IOPS of the volume.
Use max for the maximum throughput for the current number of IOPS.
To increase the root volume to 4000 IOPS and 1000 MiB/s throughput, change the label to:
runs-on: sprinters:aws:ubuntu-latest:root=gp3/4000/1000
To increase the root volume to the maximum number of IOPS for its size and the maximum throughput for these IOPS, change the label to:
runs-on: sprinters:aws:ubuntu-latest:root=gp3/max/max
You can adjust the size and performance of the temp volume by modifying the label.
4 GiB gp3 volume with 3000 IOPS and 150 MiB/s throughput.
Sizes from 1 GiB to 16384 GiB are supported.
Only gp3 volumes are supported for now.
Between 3000 and 16000 IOPS are supported, depending on the size of the volume.
Use max for the maximum number of IOPS for the current volume size.
Between 125 and 1000 MiB/s are supported, depending on the number of IOPS of the volume.
Use max for the maximum throughput for the current number of IOPS.
To set the temp size to 64 GiB, change the label to:
runs-on: sprinters:aws:ubuntu-latest:temp=64
To set the temp size to 64 GiB and max out the volume throughput, change the label to:
runs-on: sprinters:aws:ubuntu-latest:temp=64/gp3/3000/max
In order to react more quickly to instances becoming unhealthy, runners publish lifecycle events to Sprinters.
events=true|false
true
To disable the instance lifecycle events publishing (at the cost of longer timeouts when an instance becomes unhealthy or is terminated as part of a spot capacity reclaim), change the label to:
runs-on: sprinters:aws:ubuntu-latest:events=false