Controlling access to larger runners

About runner groups

To control access to runners at the organization level, organizations using the GitHub Team plan can use runner groups. Organization administrators can configure access policies that control which repositories in an organization have access to the runner group.

When you grant access 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. Runners can only be in one group at a time. You can move runners from the default group to another group. 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."

Default group for larger runners

Organizations and enterprises with access to larger runners will automatically receive a default runner group called "Default Larger Runners" that includes 4 runners of varying sizes. The runners in this group are pre-configured and ready for immediate use. In order to use the runners in this group, you will need to add the label corresponding to the runner of your choice to your workflow file. See the table below for labels. For more information on how to use labels, see "Using larger runners."

Default Runners

Description	Label	Image
4-cores Ubuntu Runner	ubuntu-latest-4-cores	Ubuntu - Latest
8-cores Ubuntu Runner	ubuntu-latest-8-cores	Ubuntu - Latest
16-cores Ubuntu Runner	ubuntu-latest-16-cores	Ubuntu - Latest
8-cores Windows Runner	windows-latest-8-cores	Windows Server - Latest

The default larger runner group is created at the billing entity level. If your organization is part of an enterprise account, the group will be managed on the enterprise level. If your organization does not fall under an enterprise, the group is managed on the organization level.

You will not be billed for these runners until you use them in your workflows. Once these runners are used, billing works as it normally does. For more information on billing, see "Using larger runners."

The default access for a larger runner group at the enterprise level is set to automatically share with all organizations in the enterprise, but not all repositories. Organization admins will need to share the default larger runner group with each repository separately. For larger runner groups at the organization level, the default access is set to automatically share the group with all repositories. For more information on how to change access policies, and where to view the default larger runner group, see "Changing the access policy of a runner group."

Creating a runner group for an organization

All organizations have a single default runner group. Organizations using the GitHub Team plan can create additional groups. Organization admins can allow individual repositories access to a runner group. For information about how to create a runner group with the REST API, see "Actions."

Runners are automatically assigned to the default group when created, and can only be members of one group at a time. You can move a runner from the default group to any group you create.

When creating a group, you must choose a policy that defines which repositories have access to the runner group.

1. On GitHub.com, 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 the access policy of a runner group

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

Changing what organizations or repositories can access a runner group

1. Navigate to the main page of the repository or 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. For runner groups in an organization, under "Repository access," use the dropdown menu to click Selected organizations.

   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.

   Warning

   We recommend that you only use self-hosted runners with private repositories. This is because forks of your public repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow.

   For more information, see "About self-hosted runners."

Changing the name of a runner group

1. Navigate to the main page of the repository or 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.

Moving a 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. Navigate to the main page of the organization where your self-hosted runner is registered.

2. 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 runner group

Runners are automatically returned to the default group when their group is removed.

1. Navigate to the main page of the repository or 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. Any runners still in this group will be automatically moved to the default group, where they will inherit the access permissions assigned to that group.