How to Target Jobs With Runner Labels in GitHub Actions

A job runs on any runner that carries every label listed in runs-on, so labels are how you steer jobs to the right hardware.

Add custom labels at registration with --labels, then list them as an array in runs-on. A runner must have all listed labels to be eligible.

Steps

• Register runners with descriptive labels (gpu, arm64, prod).
• List all required labels as an array in runs-on.
• A runner needs every label in the list to match (AND, not OR).
• Add or remove labels later from the runner settings UI.

Register with labels

./config.sh --url <url> --token <token> \
  --labels self-hosted,linux,gpu,cuda-12

Match in a workflow

jobs:
  train:
    runs-on: [self-hosted, linux, gpu, cuda-12]
    steps:
      - run: nvidia-smi && python train.py

Gotchas

• runs-on labels are matched with AND; a typo means no runner matches and the job queues forever.
• The implicit self-hosted, OS, and arch labels cannot be removed.

Related guides