Runner Labels & Routing

~9 min · labels, routing, matchmaking

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

How GitHub picks a runner

When a job declares runs-on: [self-hosted, gpu, linux], GitHub finds every runner with all three labels. If multiple runners qualify, the first idle one wins. If none, the job queues until one becomes available.

Labels you'll routinely need

Trust tier — trusted (only own-org code) vs untrusted (public PRs).
Resource shape — gpu, gpu-h100, large-mem, fast-disk.
Location — region-us, region-kr, internal-network.
Capability versioning — cuda12, node22. When you upgrade the runner image, change the label so old workflows still target the old runner during transition.

Group routing

Beyond labels, runners can be in runner groups at the org level. A group restricts which workflows / repos can use that runner. Use groups when one runner pool serves multiple repos with different trust levels.

Code

Match-the-strongest-runner pattern·yaml

  fast-test:
    # Prefer a fast runner if available; fall back to any
    runs-on: [self-hosted, fast-disk, linux]
    steps:
      - run: pytest

  any-runner:
    runs-on: [self-hosted, linux]
    steps:
      - run: pytest

External links

Exercise

Document your runner fleet's labels in a README. For each runner, list its labels, what kinds of jobs it should pick up, and who maintains it. Update labels if any are missing or stale.