Setup RunsOn

RunsOn is our recommended solution for self-hosted GitHub runners. It provides zero-infrastructure runner management with simple setup and cost-effective pay-per-use pricing.

Why RunsOn?

We evaluated multiple self-hosted runner solutions and recommend RunsOn for most deployments:

Zero Infrastructure Management

No EC2 instances, Lambda functions, or Kubernetes clusters to maintain. RunsOn handles all infrastructure automatically.

Simple Setup

Deploy a single Terraform component, install a GitHub App, and you're ready to go. No complex configurations or ongoing maintenance.

Cost Effective

Pay only for compute time you use. Automatic spot instance pricing keeps costs low with no idle infrastructure.

No Kubernetes Required

Unlike Actions Runner Controller (ARC), RunsOn works without EKS. Perfect for organizations that don't need Kubernetes.

Organization-Wide Configuration

Define runner configurations once in a central .github repository and inherit across all repos.

Quick Start

• Acquire a RunsOn license
• Vendor the required components
• Deploy the RunsOn component
• Install the GitHub App
• Configure your workflows to use the runners

Network Requirements

RunsOn runners need network access to deploy resources in your private network, such as EKS clusters, Aurora databases, or any other VPC-based resources.

With the reference architecture, we deploy RunsOn into the existing VPC in the core-auto account. This VPC is already configured with Transit Gateway and has access to the private network across all accounts.

NOTE:

If you opt to deploy RunsOn into a separate VPC, you will need to connect that VPC to Transit Gateway in order to access the private network.

1 Acquire a RunsOn License

RunsOn requires a license key to operate. We recommend the Commercial License for production deployments. A free 15-day trial is available if you need to evaluate RunsOn first.

License Options:

License	Cost	Use Case
Demo	Free (15 days)	Evaluation and testing
Commercial (recommended)	$300/year	Production deployments
Sponsorship	$1,500/year	Source code access + dedicated support

Non-profit organizations qualify for free non-commercial licenses.

Once you have your license key, add it to your Atmos stack catalog at stacks/catalog/runs-on/defaults.yaml in the LicenseKey parameter.

Working with Cloud Posse?:

Share your RunsOn license key via 1Password and we'll add it to your stack catalog for you.

For more details, see the RunsOn Pricing page.

2 Vendor RunsOn Component

Vendor the required components using the included Atmos workflow:

Loading workflow...

3 Deploy RunsOn Component

Deploy the RunsOn component using the included Atmos workflow:

Loading workflow...

4 Install GitHub App

After deployment, follow these steps to install the GitHub App:

1. Check the Terraform outputs for RunsOnEntryPoint
2. Use the provided URL to install the GitHub App
3. Follow the prompts to complete the installation in your GitHub Organization
4. Ensure you have the necessary permissions in GitHub to install the app

5 Configure Workflows

NOTE:

These workflows should already be configured as part of the reference architecture package. You can confirm the following configuration is in place.

Update your GitHub Actions workflow files to use the self-hosted runners:

jobs:
  build:
    runs-on:
      - "runs-on=${{ github.run_id }}"
      - "runner=terraform" # Note `terraform` is a runner group name defined by a RunsOn configuration
      ## If no configuration is present, use
      # - "runner=2cpu-linux-x64"
      ## Optional Tags
      # - "tag=${{ inputs.component }}-${{ inputs.stack }}"
    steps:
      - uses: actions/checkout@v3
      # Add your build steps here

For more information on available runner types and configurations, check the RunsOn: Runner Types documentation.

6 (Optional) Setup a RunsOn Repo or Organization Configuration

In your Repository you can add a file to configure RunsOn. This can also extend the configuration for the Organization.

NOTE:

This snippet below is an extremely simplified example. If you want to see what Cloud Posse uses as a starting point, checkout our configuration here.

Reference architecture users should see an included default configuration in their .github folder in the infrastructure repository.

Here's a sample configuration. We recommend storing this in a centralized .github repository so you can define a shared runs-on configuration that you can use across all repositories, without duplicating it in each one. This is especially useful when managing many repositories.

MyOrg/.github/.github/runs-on.yml

runners:
  terraform:
    image: ubuntu22-full-x64
    disk: default
    spot: price-capacity-optimized
    retry: when-interrupted
    private: false
    ssh: false
    cpu: [2, 32]
    ram: [8, 64]
    tags:
      - "gha-runner:runs-on/terraform"

To use your organization's shared configuration in an individual repository, you need to define a local configuration that uses the _extends keyword to inherit from the centralized setup — it won't be applied automatically.

MyOrg/MyInfraRepo/.github/runs-on.yml

# See https://runs-on.com/configuration/repo-config/
_extends: .github
terraform:
  cpu: [4, 32] # example override

Troubleshooting

GitHub Action Runner Not Found

First determine if the Workflow or the Runner is the issue, sometimes the workflow doesn't kick off because it is on a feature branch and not on the default.

If the workflow kicks off but is waiting on a runner, checkout RunsOn Troubleshooting as they have great docs on figuring out why a runner is not available.