Skip to content
RunsOn
Blog

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)
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:

Inputs for RunsOn stack

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.

Create RunsOn stack

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:

CloudFormation Output

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”:

Register GitHub App

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

Create GitHub App

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

Set permissions for GitHub App

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

Success

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:

Allow repository-level runners in organization 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.

Stack parameters

GithubOrganization

  • Type: String
  • Description: Name of your GitHub organization. For instance if your GitHub organization lives at https://github.com/my-org, then the value of this parameter should be: my-org.
  • MinLength: 1

LicenseKey

EmailAddress

  • Type: String
  • Description: Email address for cost and alert reports.
  • MinLength: 1

AlertTopicSubscriptionHttpsEndpoint

SSHCidrRange

  • Type: String
  • Default: 0.0.0.0/0
  • Description: CIDR range for SSH access (mainly useful when Private=false). By default, only repository collaborators with admin permission will be able to SSH into the runner instances.
  • MinLength: 1

Private

  • Type: String
  • Default: false
  • AllowedValues:
    • true
    • false
  • Description: Enable (true) or disable (false) private subnets. Note that enabling will create 3 managed NAT gateways, with the corresponding costs.

DefaultAdmins

  • Type: String
  • Default: ""
  • Description: Comma-separated list of GitHub usernames that will always be granted SSH access to all the runner instances (if SSH access is enabled). If blank, only repository collaborators with push permission will be able to SSH into the runner instances.

AppEc2QueueSize

  • Type: Number
  • Default: 2
  • MinValue: 1
  • Description: Rate limit for launching instances, per second. New AWS accounts come with a default of 2 RunInstances call/s, so only increase if you have requested a higher limit from AWS.

AppAlarmDailyMinutes

  • Type: Number
  • Default: 4000
  • Description: Trigger an alarm if the cumulative number of minutes consumed during a day is over that number.

AppCPU

  • Type: Number
  • Default: 256
  • Description: CPU units for RunsOn service (256 or higher). If you have many workflows, you may need to increase this (512, 1024, etc.).

AppMemory

  • Type: Number
  • Default: 512
  • Description: Memory in MB for RunsOn service (512 or higher). If you have many workflows, you may need to increase this (1024, 2048, etc.).

RunnerDefaultDiskSize

  • Type: Number
  • Default: 40
  • MinValue: 40
  • Description: Disk size in GB for default runners.

RunnerDefaultVolumeThroughput

  • Type: Number
  • Default: 400
  • MinValue: 125
  • MaxValue: 1000
  • Description: Volume throughput in MiB/s for default runners (helps with faster boot times, but costs more).

RunnerLargeDiskSize

  • Type: Number
  • Default: 80
  • MinValue: 40
  • Description: Disk size in GB for large runners.

RunnerLargeVolumeThroughput

  • Type: Number
  • Default: 750
  • MinValue: 125
  • MaxValue: 1000
  • Description: Volume throughput in MiB/s for large runners (helps with faster boot times, but costs more).

CostReportsEnabled

  • Type: String
  • Default: true
  • AllowedValues:
    • true
    • false
  • Description: Enable or disable cost reports sent by email.

EC2InstanceCustomPolicy

  • Type: String
  • Default: ""
  • Description: Optional managed IAM Policy ARN to assign to the EC2 runner instances.

ECInstanceDetailedMonitoring

  • Type: String
  • Default: false
  • AllowedValues:
    • true
    • false
  • Description: Enable or disable detailed monitoring for EC2 instances (can incur additional costs).