Installing RunsOn

Deploy self-hosted GitHub Actions runners to your AWS account

This guide walks you through deploying RunsOn to your AWS account using CloudFormation. The entire process takes approximately 10 minutes.

Prerequisites#

Before you begin, ensure you have:

AWS account - A dedicated AWS account is recommended for better isolation
GitHub organization or personal account - Where you want to install RunsOn
License key - Free for non-commercial use, or start a 15-day trial at runs-on.com
AWS permissions - Ability to create CloudFormation stacks with IAM resources

Step 1: Deploy the CloudFormation stack#

RunsOn is deployed via a CloudFormation template. Choose your preferred AWS region and click the corresponding link:

Region	Deploy Link
US East (N. Virginia)	`us-east-1`
US East (Ohio)	`us-east-2`
US West (Oregon)	`us-west-2`
EU (Ireland)	`eu-west-1`
EU (Paris)	`eu-west-3`
EU (Frankfurt)	`eu-central-1`
EU (London)	`eu-west-2`
Asia Pacific (Tokyo)	`ap-northeast-1`
Asia Pacific (Singapore)	`ap-southeast-1`
Asia Pacific (Sydney)	`ap-southeast-2`

Visit runs-on.com/guides/install for direct CloudFormation quick-create links.

Step 2: Configure the stack#

Fill in the CloudFormation parameters:

Required parameters:

Parameter	Description
Stack name	Must be lowercase (e.g., `runs-on-production`)
GitHub organization	Your GitHub org or personal account name
License key	Your RunsOn license key or SSM parameter reference
Alert email	Email address for cost and alert reports

Optional parameters:

Parameter	Description	Default
GitHub Enterprise URL	For GitHub Enterprise Server installations	Empty (github.com)
Networking stack	VPC configuration	`embedded` (recommended for testing)
Instance types	Allowed EC2 instance families	All supported types

Stack names must be lowercase for proper resource deployment. Names like RunsOn-Prod will cause deployment failures.

Step 3: Create the stack#

Review your configuration
Check the acknowledgment box for IAM resource creation
Click Create stack
Wait for the stack to reach CREATE_COMPLETE status (approximately 5 minutes)

Step 4: Register the GitHub App#

After the stack completes:

Navigate to the Outputs tab in CloudFormation
Find the RunsOnEntryPoint URL
Open the URL in your browser
Click Register app

This creates a private GitHub App stored only in your AWS account. No credentials are shared with third parties.

The GitHub App registration only needs to be done once. It creates a private app within your GitHub organization that handles authentication between GitHub and your RunsOn deployment.

Step 5: Enable self-hosted runners#

In your GitHub organization settings:

Navigate to Settings > Actions > General
Under Fork pull request workflows, enable Run workflows from fork pull requests if needed
Under Workflow permissions, configure as appropriate for your security requirements

Step 6: Verify the installation#

Confirm your SNS subscription by clicking the link in the confirmation email. This enables cost and alert reports.

Test your installation with a simple workflow:

1
name: Test RunsOn
2
on: workflow_dispatch
3
4
jobs:
5
  test:
6
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
7
    steps:
8
      - name: Verify runner
9
        run: |
10
          echo "Running on RunsOn!"
11
          uname -a
12
          nproc
13
          free -h

Run this workflow manually from the Actions tab. If successful, you'll see the job execute on a RunsOn-managed EC2 instance.

Networking options#

RunsOn supports several networking configurations:

Embedded (default)

Creates a new VPC with public subnets. Recommended for testing and simple deployments.

Existing VPC

Reuse an existing VPC by providing subnet IDs. Ideal for production environments with established networking.

Private subnets

Deploy runners in private subnets with NAT gateway access. Required for environments without public IP assignments.

VPC peering

Connect RunsOn VPC to other VPCs for accessing internal resources.

Troubleshooting#

Stack creation fails

Verify your license key is correct
Ensure stack name is lowercase
Check AWS service quotas for EC2 instances

GitHub App registration fails

Verify you have organization admin permissions
Check that the entry point URL is accessible
Review CloudFormation outputs for errors

Jobs not starting

Confirm the GitHub App is installed on your repository
Check that self-hosted runners are enabled in organization settings
Review CloudWatch logs for the RunsOn service

Next steps#

Configure runners with custom resources
Set up caching for faster builds
Review best practices for production deployments