What Is a Runner Label? How Jobs Choose Their Runner
A runner label is a tag attached to a runner; a job uses runs-on to request runners with matching labels, which is how CI decides where each job goes.
Labels are the routing layer of CI. A job says "I need a runner with these labels" and the service hands it to a runner that matches. Get labels wrong and a job can sit queued forever waiting for a runner that does not exist.
How labels route jobs
Each runner advertises labels - built-in ones like self-hosted, linux, x64, plus any custom ones you add. A job's runs-on lists required labels, and the service only assigns the job to a runner that has all of them.
Built-in vs custom labels
Built-in labels describe the OS and architecture automatically. Custom labels let you route specific jobs to specific capacity - for example a gpu label for ML jobs or a provider label to send jobs to a managed fleet.
The classic mismatch failure
If a job requests a label no online runner offers, it queues indefinitely with "waiting for a runner". A typo, a decommissioned runner, or a removed label all produce the same stuck-queued symptom.
Labels and migration
Switching runner providers is often just a label change: point runs-on at the new provider's label and the same workflow runs on the new fleet. Latchkey adoption typically means swapping the runs-on label.
Debugging a label problem
When a job sits queued, list the labels your online runners actually advertise and compare them to the runs-on request. The fix is almost always making the two match - correcting a typo, bringing a runner online, or restoring a removed label.
Key takeaways
- A runner label tags a runner so jobs can request it via runs-on.
- A job runs only on a runner that has all its required labels.
- Requesting a label no runner offers queues the job indefinitely.
- Migrating runner providers is often just a runs-on label change.