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.
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).
0. Preflight checks
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:
[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:
RunsOn can work without this role, but you won’t be able to use spot instances.
1. Select your AWS region
To get started, simply select one of the regions below. This will redirect you to the CloudFormation interface:
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-v2.6.1.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:
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:
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.
Resources
- All stack configuration parameters.
- Troubleshooting guide.