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
Lookup your 12-digit AWS account ID (ex.: 123456789012
) and adjust it to:
runs-on: sprinters:aws/123456789012:ubuntu-latest
Congratulations! Your GitHub Actions job is fully set up and will execute with Sprinters on AWS going forward.
The label 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/123456789012:ubuntu-latest
The label in the example above tells Sprinters to connect to AWS account 123456789012
(using the default sprinters-role
role)
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).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.This specification can be customized 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/111122223333/my-custom-role-name:ubuntu-22.04:eu-central-1/subnet-0123456789abcdef0:m7i.24xlarge:temp=64
Sprinters will connect to the 111122223333
AWS account using the cross-account role named my-custom-role-name
and
launch a runner using the ubuntu-22.04
image in the eu-central-1
region
within the subnet-0123456789abcdef0
subnet 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 must include the AWS account ID where the runner instance is launched in the label.
Optionally you can also customize the name of IAM Role that Sprinters uses to connect to your AWS account by appending it to the label.
Format: aws
/aws-account-id/iam-role-name
Default: aws
/aws-account-id/sprinters-role
To use the 112233445566
AWS account ID and the default sprinters-role
role name, change the label to:
runs-on: sprinters:aws/112233445566:ubuntu-latest
To use the 112233445566
AWS account ID and my-custom-role-name
as the role name, change the label to:
runs-on: sprinters:aws/112233445566/my-custom-role-name:ubuntu-latest
You can set the image for the runner by replacing the one in the label.
Format: image-name
Default: ubuntu-latest
Type | 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 |
Type | 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/123456789012:minimal
You can specify where the runner instance is launched by appending a placement config to the label.
This placement config specifies the region, availability zone and subnet id of the instance.
At least one of region and availability zone must be specified. subnet id is optional.
All parts are separated by a /
.
Format: aws-region/aws-availability-zone/aws-subnet-id
Default: 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 |
More regions will be added soon. To request support for a specific region, file an issue in the issue tracker.
To set the region to eu-central-1
and run using the minimal
image, change the label to:
runs-on: sprinters:aws/123456789012:minimal:eu-central-1
To use the eu-central-1c
availability zone, change the label to:
runs-on: sprinters:aws/123456789012: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/123456789012: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.
Format: aws-instance-type
Default: 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 |
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 |
---|---|
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 |
t4g | t4g.nano , t4g.micro , t4g.small , t4g.medium , t4g.large , t4g.xlarge , t4g.2xlarge |
More instance families will be added soon. To request support for a specific instance family, file an issue in the issue tracker.
To set the instance type to m7i.8xlarge
, change the label to:
runs-on: sprinters:aws/123456789012: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.
Format: spot=auto|true|false
Default: auto
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/123456789012: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.
Format: profile=instance-profile-name
Default: none
To associate your instance with the my-instance-profile
instance profile, change the label to:
runs-on: sprinters:aws/123456789012:ubuntu-latest:profile=my-instance-profile
See also: Accessing AWS Resources for more info.
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
To set the temp disk space to 512
GiB, change the label to:
runs-on: sprinters:aws/123456789012:ubuntu-latest:temp=512
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
To set the swap size to 64
GiB, change the label to:
runs-on: sprinters:aws/123456789012:ubuntu-latest:swap=64
Join our monthly email newsletter.
We’ll share product updates, new releases and other tidbits we think you’ll find interesting.