Quickstart
From zero to a cached, 10x-cheaper GitHub Actions build running in your own AWS account.
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:
- Launch the stack in your AWS region, with one click.
- Create the stack with your GitHub organization, license key, and an alert email, then confirm the alert subscription email AWS sends you.
- Register the GitHub App from the
stack’s
RunsOnEntryPointoutput, and check the RunsOn status page.
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:
- Create the GitHub credential: a GitHub App installed on your organization, or a classic PAT for an enterprise.
- 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. - Run
terraform apply, then confirm the alert subscription email AWS sends you.
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:
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.
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.
3. Make it fast with caching (recommended)#
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:
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.
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.