Workloads
A workload is a named pool of ephemeral runners
bound to one GitHub organization or personal account. It carries the
targeting (org, labels, name prefix), the sizing (minRunners /
maxRunners), the isolation runtime, an optional cache key, and a
host pool (target hosts and a per-host cap). It does not carry the runner’s
shape — for that it references a runner profile.
One account backs many workloads; one workload serves exactly one account. The reconciliation loop keeps the live runner count in line with what each workload wants.
Sizing the pool
Section titled “Sizing the pool”Two numbers bound every workload:
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 workloads
Section titled “Routing jobs between workloads”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 workload a distinct label, match it in
runs-on, and jobs land only where you intend.
The runner’s shape lives in a profile
Section titled “The runner’s shape lives in a profile”A workload says how many runners and where; a runner profile says what each runner looks like — image, memory and CPU limits, custom env, pull policy, and an optional registry credential. Two workloads (say, two different orgs) can reference the same profile, so you define the shape once and reuse it.
Cache is picked by key, owned by the host
Section titled “Cache is picked by key, owned by the host”Cache volumes belong to the host, not the workload. A workload selects one with an optional cache key. The effective volume is resolved per host, org, and key: no key gives one shared cache per organization on that host; a key gives a separate warm cache. Same-org workloads using the same key share a warm cache on a host; different organizations never share one. See Caching.