Skip to main content
Sponsor @cloudposse

Runs On - Self-Hosted Runners

This guide explains how to set up and manage self-hosted runners using the Runs On component. Self-hosted runners provide more control over the execution environment, allowing you to run workflows on your own infrastructure.

note

GitHub-OIDC is not required to deploy Runs On, but it is required for several components to be deployed on or to via SelfHosted Runners. For example, your runners cannot push to ECR without GitHub-OIDC.

Quick Start

  1. Vendor the required components
  2. Deploy the Runs On component
  3. Install the GitHub App
  4. Configure your workflows to use the runners

1 Vendor Runs On Component​

Vendor the required components using the included Atmos workflow:

vendor:
These are the commands included in the vendor workflow in the examples/snippets/stacks/workflows/github.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

2 Deploy Runs On Component​

Deploy the Runs On component using the included Atmos workflow:

deploy/runs-on:
These are the commands included in the deploy/runs-on workflow in the examples/snippets/stacks/workflows/github.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

3 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

4 Configure Workflows​

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.

5 (Optional) Setup a RunsOn Repo or Organization Configuration​

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

note

Please 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

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 Runs On Troubleshooting as they have great docs on figuring out why a runner is not available.