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.