Configuration
How RunsOn is configured — per-job labels and repo/stack files in Flex, Terraform-owned runner catalogs in Fleet.
RunsOn has three configuration layers. Which ones you use, and who owns them, depends on the product: in Flex workflow authors pick runner shapes per job, while in Fleet the platform team curates a fixed catalog in Terraform.
The three layers#
| Layer | What it controls | Flex | Fleet |
|---|---|---|---|
| Stack | Install-time platform settings: networking, IAM, observability, budgets, integrations | CloudFormation parameters or Terraform | Terraform module inputs |
| Repo / org | Reusable runner definitions, images, pools, admins, shared across repos | .github/runs-on.yml (and .github-private) | Runner catalog in Terraform |
| Per job | The runner shape and capabilities for a single job | runs-on: job labels | Fleet label selects a pre-approved fleet |
Flex#
Flex is configured bottom-up by workflow authors, with org-wide defaults available:
- Job labels — choose family, CPU, RAM, image, disk, spot, and
extrasper job. See Job labels. - Repo-level config — define reusable custom runners, images, pools, and admins in
.github/runs-on.yml, optionally inheriting from a private.github-privaterepo. See Repo-level config. - Stack config — install-time CloudFormation parameters (or Terraform inputs) for networking, IAM, observability, budgets, and integrations. See Flex configuration.
Fleet#
Fleet inverts the ownership: the platform team defines an approved catalog of runner fleets in Terraform, and workflows simply target a fleet label. CPU, RAM, family, image, and extras move from per-job labels into Terraform-reviewed catalog entries. See Runner fleets.
Flex concepts imported into Fleet#
Fleet reuses several Flex building blocks, but it changes who makes the runner choice. Flex lets each workflow describe the runner it needs. Fleet asks the platform team to publish a smaller catalog of approved runner fleets.
| Flex concept | Fleet equivalent | What changes |
|---|---|---|
| Ephemeral EC2 runner | Ephemeral EC2 runner launched for a scale-set job | The runner still lives in your AWS account and terminates after the job. |
| Runner image | images catalog entry | Use built-in image names when possible; define images only for custom AMIs or lookup rules. |
| Runner shape | runners catalog entry | CPU, RAM, family, image, and extras move from per-job labels into Terraform-reviewed catalog entries. |
| Shared runner fleet | fleets entry | The runner fleet is the public workflow target and points at one runner shape. |
| App sizing | app_size | The same small, medium, high, and xhigh presets size the worker and internal concurrency. |
| Cache bucket and bootstrap | Fleet module cache storage and runner bootstrap | Fleet runners use the same AWS-owned bootstrap path and cache storage, but cache policy is runner-fleet owned instead of ad hoc per job. |
| Cost allocation tags | cost_allocation_tag, tags, runner_custom_tags | Fleet adds fleet identity tags so spend can be grouped by runner fleet and stack. |
Fleet-specific concepts#
| Fleet concept | Why it matters |
|---|---|
| GitHub runner scale set | GitHub routes jobs to the scale set before Fleet launches matching EC2 capacity. |
| Runner fleet | The named capacity target that workflow authors use with runs-on/fleet=<fleet-name>/env=<environment>. |
| Runner group | The GitHub access boundary. It controls which repositories, organizations, or workflows can use a runner fleet. |
| Active boundary | One Fleet runtime targets one organization installation or one enterprise boundary. |
| Assigned-job demand | Fleet launches capacity from GitHub scale-set demand, not from workflow-job webhooks. |
Modeling guidance#
Start with one runner fleet per workload class, not one runner fleet per repository.
Good first runner fleets:
linux-smallfor normal test and lint worklinux-largefor memory-heavy buildslinux-arm64when ARM builds are part of the platform contractdeploywhen deployment workflows need a separate runner group
Avoid copying every Flex label into a runner fleet. If a workflow regularly needs one-off GPU, disk, nested virtualization, or unusual image choices, keep that workload on Flex until it becomes a common platform runner fleet.