Installation guide

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 ops@runs-on.com or book an onboarding call ↗.

CloudFormation

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-v3.1.0.yaml

2. Create the stack

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

You must fill the fields under Main configuration [required]:

• the name of your GitHub organization or personal account where you want to install RunsOn (e.g. my-org).
• the license key for RunsOn, either as a plain text value or a reference to an SSM parameter. You can get one here, with a 15-day free trial.
• an email address where cost & alert reports will be sent.
• optionally, the RunsOn Environment name if you intentionally operate multiple environments.

Finally, acknowledge the CloudFormation capabilities and transforms, then continue to the review screen. Note that the stack will create a dedicated IAM role for the RunsOn service, with the most restricted set of permissions required.

On the final review screen, click “Submit” to start creating the 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:

3. Register the GitHub app

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. Update your workflows

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

Terraform / OpenTofu

RunsOn provides an official Terraform module for deploying and managing your RunsOn infrastructure as code.

For v3, Terraform / OpenTofu is also the recommended path whenever you need capabilities that are no longer exposed by the built-in CloudFormation template, such as GHES support, reusing an existing VPC, or IAM permission boundaries.

Official Terraform module

The module is available on both registries:

• Terraform Registry ↗
• OpenTofu Registry ↗

The recommended v3 approach is to use the explicit Flex submodule:

module "runs_on_flex" {
  source  = "runs-on/runs-on/aws//flex"
  version = "v3.1.0"

  github_organization = "my-org"
  license_key         = "your-license-key"
  email               = "alerts@example.com"
  app_size            = "small"
  app_budget_daily_usd = 10

  vpc_id             = "vpc-xxxxxxxx"
  public_subnet_ids  = ["subnet-pub1", "subnet-pub2"]
  private_subnet_ids = ["subnet-priv1", "subnet-priv2"]
}

output "runs_on_ingress_url" {
  description = "RunsOn setup and webhook ingress URL"
  value       = module.runs_on_flex.ingress.url
}

output "runs_on_getting_started" {
  description = "RunsOn post-apply setup instructions"
  value       = module.runs_on_flex.stack.getting_started
}

For full documentation, available variables, and examples, see the official module on GitHub ↗.

The Terraform module should be used in the following cases:

• Your organization already uses Terraform to manage AWS infrastructure, and you want to use the same tool to manage your RunsOn stack.
• You want full control over how the networking stack is configured, and/or want to reuse an existing VPC.
• You need GHES support or IAM permission boundaries.

Resources

• All stack configuration parameters.
• Migrate from v2 to v3.
• All job labels available for your workflows.
• The documentation for Linux runners.
• Troubleshooting guide.
• Cost control guide.
• CLI to manage and troubleshoot your RunsOn stack.
• Instance finder ↗ - quickly find AWS instances matching your CPU, RAM, and architecture requirements.