Introduction

Organization runner groups let teams share self-hosted runners across repositories without exposing every runner to every project. When a repository is not allowed to use a runner group, the job often looks like a generic no-runner problem even though the runner is online. The real issue is that the repository is outside the group's access policy or the workflow points at the wrong group and labels.

Symptoms

  • Workflow jobs remain queued even though self-hosted runners are online
  • GitHub reports that the runner group does not include the repository
  • The same workflow succeeds in one repository but fails in another
  • Repository migration or org policy changes broke runner access without changing the YAML

Common Causes

  • The runner group is limited to selected repositories and this repository is not included
  • The workflow references a group name or label combination that no runner actually satisfies
  • Organization Actions policy restricts repository use of self-hosted runners
  • A repository was transferred, renamed, or recreated and lost previous runner-group access

Step-by-Step Fix

  1. 1.Confirm the exact runner group and labels the job requests
  2. 2.Start from the workflow YAML so you know whether the failure is access-related or simply a label mismatch.
yaml
runs-on:
  group: deploy-runners
  labels: [linux, x64]
  1. 1.List runner groups and inspect repository access
  2. 2.Verify that the repository is actually attached to the intended organization runner group.
bash
gh api orgs/{org}/actions/runner-groups
gh api orgs/{org}/actions/runner-groups/{group-id}/repositories
  1. 1.Add the repository to the selected runner group or adjust group visibility
  2. 2.If the group is intentionally restricted, add this repository explicitly instead of broadening access more than necessary.
bash
gh api orgs/{org}/actions/runner-groups/{group-id}/repositories \
  --method PUT \
  -f selected_repository_ids='[123456]'
  1. 1.Verify the workflow routes to a runner that is both allowed and online
  2. 2.A repository can have access to the group and still fail if no runner in that group matches the requested labels.

Prevention

  • Keep runner-group membership managed through code or documented operational procedures
  • Standardize label conventions so workflows do not drift away from runner reality
  • Review repository access whenever repositories are transferred, renamed, or split
  • Prefer least-privilege runner-group visibility instead of making all runners available org-wide