Skip to main content

Managing access to self-hosted runners using groups

You can use policies to limit access to self-hosted runners that have been added to an organization or enterprise.

About self-hosted runner groups

Self-hosted runner groups are used to control access to self-hosted runners at the organization and enterprise level. Enterprise owners can configure access policies that control which organizations in an enterprise have access to the runner group. Organization owners can configure access policies that control which repositories in an organization have access to the runner group.

When an enterprise owner grants an organization access to a runner group, organization owners can see the runner group listed in the organization's self-hosted runner settings. The organization owners can then assign additional granular repository access policies to the enterprise 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 self-hosted runner to a group."

Creating a self-hosted runner group for an organization

All organizations have a single default self-hosted runner group. Organizations within an enterprise account can create additional self-hosted groups. Organization admins can allow individual repositories access to a runner group. For information about how to create a self-hosted runner group with the REST API, see "Self-hosted runner groups."

Self-hosted 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 your enterprise, navigate to the main page of the organization.

  2. Under your organization name, click Settings.

    Organization settings button

  3. In the left sidebar, click Actions.

  4. In the left sidebar, under "Actions", click Runners.

  5. Under "Runners", click Add new, and then New group.

    Add runner group

  6. Enter a name for your runner group, and 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.

    Add runner group options

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

Creating a self-hosted runner group for an enterprise

Enterprises can add their self-hosted runners to groups for access management. Enterprises can create groups of self-hosted runners that are accessible to specific organizations in the enterprise account. Organization owners can then assign additional granular repository access policies to the enterprise runner groups. For information about how to create a self-hosted runner group with the REST API, see the enterprise endpoints in the GitHub Actions REST API.

Self-hosted runners are automatically assigned to the default group when created, and can only be members of one group at a time. You can assign the runner to a specific group during the registration process, or you can later move the runner from the default group to a custom group.

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

  1. In the top-right corner of GitHub AE, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub AE

  2. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar

  3. Under " Policies", click Actions.

  4. Click the Runners tab.

  5. Use the Add new drop-down, and select New group.

  6. Under "Group name", type a name for your runner group.

  7. To choose a policy for organization access, select the Organization access drop-down, and click a policy. You can configure a runner group to be accessible to a specific list of organizations, or all organizations in the enterprise.

    Add runner group options

  8. Click Save group to create the group and apply the policy.

Changing the access policy of a self-hosted runner group

For runner groups in an enterprise, you can change what organizations in the enterprise can access 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. In the "Runners" section of the settings page, next to the runner group you'd like to configure, click , then click Edit name and [organization|repository] access. Manage repository permissions
  2. Modify your policy options.

Changing the name of a runner group

  1. In the "Runners" section of the settings page, next to the runner group you'd like to configure, click , then click Edit name and [organization|repository] access. Manage repository permissions
  2. Change the runner group name.

Automatically adding a self-hosted runner to a group

You can use the configuration script to automatically add a new self-hosted runner to a group. For example, this command registers a new self-hosted 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 self-hosted runners are automatically assigned to the default group, and can then be moved to another group.

  1. Navigate to where your self-hosted runner is registered:

    • In an organization: navigate to the main page and click Settings.

    • If using an enterprise-level runner:

      1. In the top-right corner of GitHub AE, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub AE
  2. Navigate to the GitHub Actions settings:

    • In an organization:

      1. In the left sidebar, click Actions.
      2. In the left sidebar, under "Actions", click Runners.
    • If using an enterprise-level runner:

      1. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar
      2. Under " Policies", click Actions.
      3. Click the Runners tab.
  3. In the "Runner groups" section of the settings page, locate the current group of the runner you want to move and expand the list of group members. View runner group members

  4. Select the checkbox next to the self-hosted runner, and then click Move to group to see the available destinations. Runner group member move

  5. To move the runner, click on the destination group. Runner group member move

Removing a self-hosted runner group

Self-hosted runners are automatically returned to the default group when their group is removed.

  1. Navigate to where your self-hosted runner groups are located:

    • In an organization: navigate to the main page and click Settings.

    • If using an enterprise-level group:

      1. In the top-right corner of GitHub AE, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub AE
  2. Navigate to the "Runner groups" settings:

    • In an organization:

      1. In the left sidebar, click Actions.
      2. In the left sidebar, under "Actions", click Runners.
    • If using an enterprise-level group:

      1. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar
      2. Under " Policies", click Actions.
      3. Click the Runner groups tab.
  3. In the list of groups, to the right of the group you want to delete, click .

  4. To remove the group, click Remove group.

  5. Review the confirmation prompts, and click Remove this runner group.