Managing access to self-hosted runners using groups

About runner groups

To control access to runners at the organization level, organizations using the GitHub Team plan can use runner groups. Runner groups are used to collect sets of runners and create a security boundary around them.

When you grant access to a runner group, you can see the runner group listed in the organization's runner settings. Optionally, you can assign additional granular repository access policies to the runner group.

When new runners are created, they are automatically assigned to the default group unless otherwise specified. Runners can only be in one group at a time. You can move runners from one runner group to another. For more information, see Moving a runner to a group.

For information on how to route jobs to runners in a specific group, see Choosing the runner for a job.

Creating a self-hosted runner group for an organization

All organizations have a single default runner group. Organization owners using the GitHub Team plan can create additional organization-level runner groups.

If no group is specified during the registration process, runners are automatically added to the default group. You can later move the runner from the default group to a custom group. For more information, see Moving a runner to a group.

For information about how to create a runner group with the REST API, see REST API endpoints for GitHub Actions.

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

   

3. In the left sidebar, click Actions, then click Runner groups.

4. In the "Runner groups" section, click New runner group.

5. Enter a name for your runner group.

6. Assign a policy for repository access.

   You can configure a runner group to be accessible to a specific list of repositories, or to all repositories in the organization. By default, only private repositories can access runners in a runner group, but you can override this. This setting can't be overridden if configuring an organization's runner group that was shared by an enterprise.

7. Click Create group to create the group and apply the policy.

Changing which repositories can access a runner group

For runner groups in an organization, you can change what repositories in the organization can access a runner group.

1. Navigate to the main page of the organization where your runner groups are located.

2. Click Settings.

3. In the left sidebar, click Actions, then click Runner groups.

4. In the list of groups, click the runner group you'd like to configure.

5. Under "Repository access," use the dropdown menu to click Selected repositories.

   1. To the right of the dropdown menu, click .
   2. In the popup, use the checkboxes to select repositories that can access this runner group.

6. Click Save group.

Changing the name of a runner group

1. Navigate to the main page of the organization where your runner groups are located.
2. Click Settings.
3. In the left sidebar, click Actions, then click Runner groups.
4. In the list of groups, click the runner group you'd like to configure.
5. Enter the new runner group name in the text field under "Group name."
6. Click Save.

Automatically adding a self-hosted runner to a group

You can use the configuration script to automatically add a new runner to a group. For example, this command registers a new runner and uses the --runnergroup parameter to add it to a group named rg-runnergroup.

./config.sh --url $org_or_enterprise_url --token $token --runnergroup rg-runnergroup

The command will fail if the runner group doesn't exist:

Could not find any self-hosted runner group named "rg-runnergroup".

Moving a self-hosted runner to a group

If you don't specify a runner group during the registration process, your new runners are automatically assigned to the default group, and can then be moved to another group.

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

   

3. In the left sidebar, click Actions, then click Runners.

4. In the "Runners" list, click the runner that you want to configure.

5. Select the Runner group drop-down.

6. In "Move runner to group", choose a destination group for the runner.

Removing a self-hosted runner group

In order to remove a runner group, you must first move or remove all of the runners from the group.

1. Navigate to the main page of the organization where your runner groups are located.
2. Click Settings.
3. In the left sidebar, click Actions, then click Runner groups.
4. In the list of groups, to the right of the group you want to delete, click .
5. To remove the group, click Remove group.
6. Review the confirmation prompts, and click Remove this runner group.