Installing RunsOn

The entire RunsOn stack can be installed in 10 minutes in your AWS account and requires:

• a license key (free for non-commercial use, or 15 days trial available).
• an AWS account: we recommend that you set up RunsOn in its own dedicated AWS sub-account, to further improve isolation of your workflows.

What about GitHub API interactions?

During the installation process, a GitHub App ↗ will automatically get created for you by RunsOn. It is a PRIVATE GitHub App, only accessible to your organization, and the credentials only live in your AWS account. No one else can see it. This is in contrast to other third-party runners where you relinquish control of your workflows to a third-party GitHub App.

Some optional but useful checks before starting the installation:

[Additional check 1] Make sure you have enabled the permission to create repository-level self-hosted runners in your organization settings, under the “General” Actions settings.

Direct link:

https://github.com/organizations/<YOUR_ORG>/settings/actions

[Additional check 2] Make sure the AWSServiceRoleForEC2Spot linked role for EC2 Spot exists in your AWS account.

Amazon EC2 is supposed to ↗ create the AWSServiceRoleForEC2Spot service-linked role the first time you request a Spot Instance, but some users report that it doesn’t.

Just run the following command to make sure it exists in the AWS account where you want to install RunsOn:

aws iam create-service-linked-role --aws-service-name spot.amazonaws.com

RunsOn can work without this role, but you won’t be able to use spot instances.

If at any point you are stuck, please reach out to me at [email protected]. I can even help you get started with RunsOn for free over a screen-sharing session (it takes only 10 minutes after all).

1. Select your AWS region

To get started, simply select one of the regions below. This will redirect you to the CloudFormation interface:

🇺🇸 North Virginia (us-east-1)

🇺🇸 Ohio (us-east-2)

🇺🇸 Oregon (us-west-2)

🇮🇪 Ireland (eu-west-1)

🇫🇷 Paris (eu-west-3)

🇩🇪 Frankfurt (eu-central-1)

🇬🇧 London (eu-west-2)

🇯🇵 Tokyo (ap-northeast-1)

🇸🇬 Singapore (ap-southeast-1)

🇦🇺 Sydney (ap-southeast-2)

Or, if you prefer creating the stack manually with CloudFormation, you can use the following template URL:

https://runs-on.s3.eu-west-1.amazonaws.com/cloudformation/template.yaml

Note: RunsOn can be made available in any region that has the AppRunner service available. Please contact me if you want support for a new region.

2. Stack creation

After you click on one of the regions above, you will end up on a screen with a few inputs fields:

You must fill those fields under Required Configuration:

• the name of your GitHub organization or personal account where you want to install RunsOn (e.g. my-org).
• the license key for RunsOn. You can get one here, with a 15-day free trial.
• an email address where cost & alert reports will be sent.

Then, check the box to allow the stack creation, and proceed by clicking on “Create stack”. Note that the stack will create a dedicated IAM role for the RunsOn service, with the most restricted set of permissions required.

Once the stack creation is complete, the HTTPS URL to your RunsOn instance will be displayed in the CloudFormation stack Outputs, under the RunsOnEntryPoint output parameter:

Note

During the stack creation, you will receive an email to confirm your subscription to the cost & alert SNS topic. Make sure to confirm that subscription to ensure you receive the cost & alert emails.

3. GitHub app registration

To finish the installation, from the CloudFormation stack Outputs, simply click on the HTTPS URL for the RunsOn entrypoint, and click “Register app”:

You will then be directed to a screen where you can adjust your app name:

And then select the repositories you want this app to be installed on:

After you confirm, you will get redirected to the RunsOn service, which should display the following success screen:

4. Ready!

It’s now time to update your workflows to select one of the RunsOn runner types! For instance:

runs-on: ubuntu-latest
runs-on:
  - runs-on=${{ github.run_id }}
  - runner=2cpu-linux-x64

We recommend adding the run-id label so that the runner is pinned to this workflow run. Otherwise the job could be executed by any other RunsOn runner having the same labels, which could make debugging a bit harder if anything goes wrong.