Installation Guide

RunsOn can be installed and upgraded in a few clicks using the provided CloudFormation template.

The full installation takes about 10 minutes and will require:

• a license key (free 15 day 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.
• permission to create a GitHub App in your GitHub organization. RunsOn supports any type of GitHub account, even personal accounts.

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)

Oregon (us-west-2)

Ireland (eu-west-1)

Frankfurt (eu-central-1)

London (eu-west-2)

Tokyo (ap-northeast-1)

Sydney (ap-southeast-2)

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,runner=2cpu-linux-x64,run-id=${{ github.run_id }}

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.

As a final check, make sure you have enabled repository-level self-hosted runners in your organization settings, under the “General” Actions settings:

Direct link to the settings page:

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

Stack cost

The stack will setup a dedicated VPC / 3 public subnets / Route table / S3 gateway endpoint / Security Group / Restricted IAM Role / SNS Topic for Alerts / AppRunner Service.

Monthly cost of the stack is ~$5/month on average, and can be as low as $1.5/month if low workflow count.