quickstart →

Quickstart

From zero to a cached, 10x-cheaper GitHub Actions build running in your own AWS account.

  1. 01 Install in AWS ~10 min
  2. 02 Run your first job 1 line
  3. 03 Turn on caching 2 lines

Before you start#

You need three things:

  • A RunsOn license key: start a 15-day trial, or get one free for non-commercial use.
  • An AWS account with admin access. A dedicated sub-account keeps your CI isolated.
  • A GitHub organization (or personal account) where you can create GitHub Apps. On an organization, that usually means an owner.

RunsOn comes in two modes. Flex, where most teams start, lets each job pick its own runner. Fleet lets a platform team publish a few standardized runner fleets. Each step has a tab for both; see Flex vs Fleet to choose.

1. Install RunsOn in your AWS account#

Flex installs as a single CloudFormation stack, in about 10 minutes:

  1. Launch the stack in your AWS region, with one click.
  2. Create the stack with your GitHub organization, license key, and an alert email, then confirm the alert subscription email AWS sends you.
  3. Register the GitHub App from the stack’s RunsOnEntryPoint output, and check the RunsOn status page.
Open the Flex install guide Every screen, step by step, with the gotchas.

Need Terraform / OpenTofu, an existing VPC, or IAM permission boundaries? Install Flex with the Terraform module instead.

Fleet installs with the official Terraform / OpenTofu module. On top of the list above, you need Terraform or OpenTofu, and a VPC with at least one public subnet:

  1. Create the GitHub credential: a GitHub App installed on your organization, or a classic PAT for an enterprise.
  2. Add the module for a single organization or an enterprise, with your license key, alert email, credential, network, a runner, and a fleet such as linux-small.
  3. Run terraform apply, then confirm the alert subscription email AWS sends you.
Open the Fleet install guide Organization and enterprise setups, runner groups, and private networking.

Every input is in the Fleet configuration reference.

2. Run your first job on RunsOn#

Replace runs-on: ubuntu-latest with a RunsOn label. Nothing else in the workflow changes:

.github/workflows/ci.yml
jobs:
build:
runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
steps:
- uses: runs-on/action@v2
- uses: actions/checkout@v7
- run: echo "Hello from RunsOn"

The label is composable — request exactly the machine you want, for example cpu=4/ram=16/family=m8a+m8i or runner=16cpu-linux-arm64. See all job labels and Linux runners.

.github/workflows/ci.yml
jobs:
build:
runs-on: runs-on/fleet=linux-small/env=production
steps:
- uses: runs-on/action@v2
- uses: actions/checkout@v7
- run: echo "Hello from RunsOn Fleet"

Workflows target a fleet by name and environment: runs-on/fleet=<fleet>/env=<environment>. The platform team decides which fleets exist; workflow authors only pick one.

If a job doesn't start 2 known issues
  • A Flex job stays queued: allow repository-level self-hosted runners in your organization’s Settings → Actions → General, and check that the GitHub App is installed on that repository.
  • A Fleet job stays queued: check that the label matches runs-on/fleet=<fleet>/env=<environment> exactly, and that the repository can use the fleet’s runner group.

More fixes in Troubleshooting, or email ops@runs-on.com.

Add extras=s3-cache to your runner label to turn on Magic Cache: RunsOn routes the GitHub Actions cache to S3 in your VPC, 5x faster than GitHub’s cache and with no size limit. Keep using actions/cache:

.github/workflows/ci.yml
jobs:
build:
runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=s3-cache
steps:
- uses: runs-on/action@v2
- uses: actions/cache@v5
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

On Fleet, add extras = ["s3-cache"] to the fleet’s runner (small-x64 in the install guide) and re-apply. Workflows keep the same label.

main.tf
runners = {
small-x64 = {
cpu = 2
family = ["m8", "r8"]
image = "ubuntu24-full-x64"
extras = ["s3-cache"]
}
}

Docker builds get the same cache when Buildx uses type=gha: see Docker layer caching. Everything else is in the Magic Cache reference.

Next steps#