How to Run a Job on a Self-Hosted Label in GitHub Actions

Self-hosted runners are selected by label, so a job lands only on a runner that carries every label you list.

List the required labels as an array in runs-on. The job runs only on a runner that matches all of them.

Steps

• Register your runner with custom labels (e.g. gpu, linux).
• Set runs-on: [self-hosted, linux, gpu] to match all of them.
• Keep labels specific so jobs do not land on the wrong machine.
• Use runner groups for org-wide access control.

Workflow

jobs:
  train:
    runs-on: [self-hosted, linux, gpu]
    steps:
      - uses: actions/checkout@v4
      - run: ./train.sh

Gotchas

• All listed labels must match; a typo means the job queues forever with no available runner.
• self-hosted is implied by custom labels but listing it explicitly is clearer.
• Latchkey provides managed labeled runners that are cheaper than DIY self-hosted and self-heal on failure.

Related guides