A runner group is a named, organization- or enterprise-level collection of runners governed as one scheduling and access boundary. It segments runners by team, capability, or workload so only approved repositories can use them. New runners join the Default group unless configured otherwise, and each runner belongs to only one group at a time. section 7.1 section 7.1.1
Use runner groups to control where jobs execute:
- Reserve specialized or costly capacity, such as GPU-enabled runners, for selected repositories instead of allowing ordinary jobs to consume it. section 7.1
- Limit a group to all repositories or a selected subset, and explicitly decide whether public repositories may use it. section 7.1
- Place a runner in a group during registration, or move it later through the web interface or REST API; running jobs finish under their original rules. section 7.1.1
- Target a hosted larger-runner group from workflow YAML when builds need more capacity; compare faster execution against higher per-minute cost. section 12.3.4
Create and target a restricted group
Create a group such as gpu-group with selected repository IDs and restricted workflows through the REST API. A workflow can then select an enterprise-provided group with runs-on.group, keeping high-capacity runners available only to intended automation. section 7.1 section 12.3.4
Listing 7.1 Creating a new runner group
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>"\
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/actions/runner-groups \
-d '{"name":"gpu-group",
"visibility":"selected",
"selected_repository_ids":[123,456],
"restricted_to_workflows": true,
"selected_workflows":
["<ORG-NAME>/<REPONAME>/.github/workflows/<WORKFLOW>.yml@main"]
}'
The API request shows a group name, selected repository visibility, and workflow restriction settings in one configuration. section 7.1
Treat public-repository access to self-hosted groups as a security decision. It is disabled by default because untrusted pull requests must not directly execute on self-hosted infrastructure. Monitor group capacity and usage as well, so access segmentation does not leave teams without available runners. section 7.1 section 7.6
