What Is a Runner Group? Organizing and Securing Runners
A runner group is a named bucket of runners with access policies that control which repositories and workflows are allowed to use them.
Once an organization has many runners, you need to control who can use what. Runner groups are the access-control layer: they let you reserve a set of runners for specific repos and keep sensitive runners off limits to others.
What a group does
A runner group bundles a set of self-hosted runners and attaches a policy: which repositories (and optionally which workflows) in the organization are permitted to send jobs to those runners. Runners not in any custom group sit in the default group.
Why groups matter
- Isolation: keep production-network runners away from untrusted repos.
- Cost control: reserve expensive GPU or large runners for the teams that need them.
- Compliance: restrict regulated workloads to approved hardware.
Groups vs labels
Labels decide which runner a job matches; groups decide which runners a repo is allowed to reach in the first place. They work together - a repo must have access to a group and the job must match a label within it.
Common pitfall
A repo that lacks access to the group holding its target runners will see jobs stuck queued, even though matching runners exist. Access policy, not just labels, can be the cause of a stuck job.
Groups on managed fleets
With a managed platform, the provider handles the underlying capacity while you still control which repos can use it. You get group-style access boundaries without operating the runners that sit inside them.
Key takeaways
- A runner group is a named set of runners with repo access policies.
- It controls which repositories can use which runners.
- Groups handle access; labels handle matching - they combine.
- Missing group access can queue jobs even when matching runners exist.