Scale sets

A scale set is a named pool of ephemeral runners bound to one GitHub organization or personal account. It is the unit you configure: pick the org, the runner image, and how big the pool may grow, and the reconciliation loop keeps that many runners alive for you.

Sizing the pool

Two numbers bound every scale set:

• minRunners — the warm floor kept ready, waiting for work.
• maxRunners — the ceiling Runaway scales up to under load.

Three combinations cover the common shapes:

• minRunners=0 — scale to zero. No runners sit idle between jobs; the pool spins up on demand and back down when the queue empties.
• minRunners=maxRunners — a fixed pool pinned at one size, never scaling.
• 0 < minRunners < maxRunners — a warm floor that absorbs the first jobs instantly and bursts up toward the ceiling when demand climbs.

Demand is measured as busy plus queued jobs — see Autoscaling.

Routing jobs between scale sets

GitHub decides which runner takes a job by matching your workflow’s runs-on against the runner’s labels. That label match is the isolation primitive — not which org a runner belongs to. Give each scale set a distinct label, match it in runs-on, and jobs land only where you intend.

Note

self-hosted is always implied, so you don’t need to list it. Be deliberate with your labels: two scale sets sharing a label will race for the same jobs.

What each scale set carries

• A persistent /cache volume of its own, mounted into every runner and surviving across runner generations — so package and browser caches stay warm even though each runner is single-use.
• Optional custom environment variables, useful for pointing package managers at a registry proxy you already run (for example npm_config_registry, PIP_INDEX_URL, or GOPROXY).

For the full set of options — pull policy, the Docker socket toggle, isolated runtimes, custom env rules, and host assignment — see the configuration guide.

Configure scale sets Every scale-set option in detail, from runner image to cache and custom env.