How to Provide Team-Scoped Runners on a Platform

Runner groups let the platform team give each team its own labeled runner pool while keeping one shared setup.

Create runner groups scoped to selected repositories and label the runners. A team targets its pool with runs-on, getting isolated capacity without managing runners itself.

Steps

• Create a runner group and restrict it to the team repos.
• Register runners into that group with a team label.
• Have the team target the label with runs-on.
• Keep the runner image standard across groups.

Workflow targeting

jobs:
  build:
    runs-on: [self-hosted, team-payments]
    steps:
      - uses: actions/checkout@v4
      - run: make build

Gotchas

• A job matches a runner only if the runner has every label listed in runs-on.
• Scope the runner group to specific repos so another team cannot borrow the pool.

Related guides