Agent GitHub Actions Self-Hosted Runner Labels and Groups

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

GitHub Actions self-hosted runner labels and groups tell agents why a job is queued, routed to the wrong machine, or failing only on private infrastructure.

## Core Explanation

Self-hosted runner failures are often routing failures. A job may require labels that no online runner currently has, a runner group may not be available to the repository, or the selected runner may differ in architecture, tools, network, or credentials from the expected environment.

Agents should inspect `runs-on`, labels, group membership, runner online and busy state, repository access, architecture, runner version, toolchain versions, ephemeral cleanup policy, and queue time before treating a self-hosted runner failure as an application bug.

## Source-Mapped Facts

- GitHub documentation says jobs.<job_id>.runs-on defines the type of machine to run a workflow job on. ([source](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job))
- GitHub documentation says jobs can target runners based on assigned labels, group membership, or a combination of both. ([source](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job))
- GitHub self-hosted runner documentation says a self-hosted runner matching all specified runs-on labels is eligible to run the job. ([source](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow))

## Further Reading

- [GitHub Choosing the Runner for a Job](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job)
- [GitHub Using Self-Hosted Runners in a Workflow](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow)