Setup

All it takes to set up Sprinters are 3 easy steps usually completed in under 5 minutes:

1. Install the Sprinters GitHub App

The very first step is to install the Sprinters GitHub App on your personal or organization account.

After you first log in to Sprinters , you will be redirected to the GitHub App installation prompt.

Select the GitHub personal or organization account where you want to install it and confirm the installation by clicking Install. The installation now proceeds and after a few seconds GitHub redirects you back to Sprinters.

Congratulations! The Sprinters GitHub App is now fully installed and activated.

See it in action

2. Setup your AWS account

To set up your AWS account, you’ll need to create an IAM policy and a cross-account IAM role.

Create the IAM policy

To set the permissions Sprinters will have, you’ll need an IAM policy.

Create the IAM policy in the AWS Console

To do so, paste this JSON policy document in the policy editor:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Regular",
            "Effect": "Allow",
            "Action": [ "ec2:RunInstances", "ec2:DescribeInstances", "ec2:DescribeSpotPriceHistory" ],
            "Resource": "*"
        },
        {
            "Sid": "RestrictCreateTagsToRunInstances",
            "Effect": "Allow",
            "Action": [ "ec2:CreateTags" ],
            "Resource": "*",
            "Condition": { "StringEquals": { "ec2:CreateAction": "RunInstances" } }
        },
        {
            "Sid": "RestrictToSprintersResources",
            "Effect": "Allow",
            "Action": [ "ec2:ModifyVolume", "ec2:TerminateInstances" ],
            "Resource": "*",
            "Condition": { "StringEquals": { "aws:ResourceTag/sprinters:sprinters": "true" } }
        }
    ]
}

Assign it the sprinters-policy name and create it. Your IAM policy is now fully set up.

See it in action

Create the cross-account IAM role

To establish trust between Sprinters and your AWS account, you’ll need a cross-account IAM role.

Create the cross-account IAM role in the AWS Console

Your role will need a custom trust policy that references your GitHub Account. Adjust the one below and paste it in the trust policy editor:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": { "AWS": "381491863103" },
            "Action": "sts:AssumeRole",
            "Condition": { "StringEquals": { "sts:ExternalId": "your-github-account-name" } }
        }
    ]
}

Assign the role the sprinters-role name and ensure it uses the sprinters-policy permission policy. Your cross-account IAM role is now fully set up.

See it in action

3. Migrate your GitHub Actions jobs to Sprinters

With Sprinters fully set up, let’s tell GitHub to run your workflow jobs on AWS instead of GitHub hosted runners.

To do so, locate the runs-on: directive in your workflow yml:

runs-on: ubuntu-latest

Lookup your 12-digit AWS account number and adjust it to:

runs-on: sprinters:aws/your-12-digit-aws-account-number:ubuntu-latest

Congratulations! Your GitHub Actions job is fully set up and will execute on AWS from now on.

See it in action

4. Run a test job

The easiest way to validate your setup, is to run a test job.

Generate a new GitHub repository from the sprinters-sh/sprinters-test template

On your new repo:

1. Edit the .github/workflows/test.yml workflow definition and replace your-12-digit-aws-account-number with your own AWS account number.
2. Run the sprinters-test workflow and inspect the workflow run logs.

You should now see:

Success! This job is running on a fresh EC2 instance in your AWS account using Sprinters!

Congratulations! You now have a fully operational Sprinters setup.

See it in action