To tell GitHub to run your workflow jobs using Sprinters on AWS instead of GitHub hosted runners,
locate the runs-on: label in your workflow yml:
runs-on: ubuntu-latest
And adjust it to:
runs-on: sprinters:aws:ubuntu-latest
This label tells Sprinters to connect to your AWS account
and launch a runner instance using the ubuntu-latest image, which 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:
t3.large (x64 with 2 vCPUs and 8 GiB RAM).14 GiB of temp disk space and 4 GiB of swap.The instance placement will be as follows:
us-east-1 region in your account’s default VPC.You can fully customize this by adding various parts to the label. The order doesn’t matter. All parts are separated by a colon (:).
Here is a more complex example:
runs-on: sprinters:aws:eu-central-1:ubuntu-22.04:m7i.24xlarge:temp=64
Sprinters will 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.
The following label parts can be added or modified to customize the image, placement and capacity of the runner instance:
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 |
Ubuntu 24.04 x64 image identical to the one available for GitHub hosted runners |
ubuntu-22.04 |
Ubuntu 22.04 x64 image identical to the one available for GitHub hosted runners |
minimal |
Minimal, fast-booting image containing only Git and Docker |
| Image | Description |
|---|---|
ubuntu-24.04-arm |
Ubuntu 24.04 arm64 image identical to the one available for GitHub hosted runners |
ubuntu-22.04-arm |
Ubuntu 22.04 arm64 image identical to the one available for GitHub hosted runners |
minimal |
Minimal, fast-booting image containing only Git and Docker |
To set the image to minimal, change the label to:
runs-on: sprinters:aws: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 |
eu-central-1 |
Frankfurt |
eu-west-1 |
Ireland |
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 minimal image in the eu-central-1 region, change the label to:
runs-on: sprinters:aws: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
You can set the AWS EC2 instance type on which launch the runner by appending it to the label.
aws-instance-type
t3.large
| Family | Sizes |
|---|---|
| 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 |
| 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 |
| m6i | m6i.large , m6i.xlarge , m6i.2xlarge , m6i.4xlarge , m6i.8xlarge , m6i.12xlarge , m6i.16xlarge , m6i.24xlarge , m6i.32xlarge |
| m7a | m7a.medium , m7a.large , m7a.xlarge , m7a.2xlarge , m7a.4xlarge , m7a.8xlarge , m7a.12xlarge , m7a.16xlarge , m7a.24xlarge , m7a.32xlarge , m7a.48xlarge |
| 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 |
| r7i | r7i.large , r7i.xlarge , r7i.2xlarge , r7i.4xlarge , r7i.8xlarge , r7i.12xlarge , r7i.16xlarge , r7i.24xlarge , r7i.48xlarge |
| t3 | t3.nano , t3.micro , t3.small , t3.medium , t3.large , t3.xlarge , t3.2xlarge |
| 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
To access resources in your AWS account without the need to store long-lived AWS credentials as GitHub Actions secrets, you can associate an IAM instance profile with your runner instance. The instance will then automatically have AWS credentials available with the permissions of the IAM role linked to the instance profile.
profile=instance-profile-name
none
To associate your instance with the my-instance-profile instance profile, change the label to:
runs-on: sprinters:aws:ubuntu-latest:profile=my-instance-profile
See also: Accessing AWS Resources for more info.
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 swap 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 swap size to 64 GiB, change the label to:
runs-on: sprinters:aws:ubuntu-latest:swap=64
To set the swap size to 64 GiB and max out the volume performance, change the label to:
runs-on: sprinters:aws:ubuntu-latest:swap=64/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
