Skip to main content

Controlling access to larger runners

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

The larger runners feature is currently in beta for organizations and enterprises using the GitHub Team or GitHub Enterprise Cloud plans, and is subject to change. To request access to the beta, visit the sign up page.

About runner groups

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

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

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 "Running jobs on your runner."

Default Runners

DescriptionLabelImage
4-cores Ubuntu Runnerubuntu-latest-4-coresUbuntu - Latest
8-cores Ubuntu Runnerubuntu-latest-8-coresUbuntu - Latest
16-cores Ubuntu Runnerubuntu-latest-16-coresUbuntu - Latest
8-cores Windows Runnerwindows-latest-8-coresWindows 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

Warning: If you are using a Fixed IP range, we recommend that you only use larger runners with private repositories. Forks of your repository can potentially run dangerous code on your larger runner by creating a pull request that executes the code in a workflow.

All organizations have a single default runner group. Organizations within an enterprise account 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 "Self-hosted runner groups."

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 and workflows 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.

    Organization settings button

  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. Assign a policy for workflow access.

    You can configure a runner group to be accessible to a specific list of workflows, or to all workflows. This setting can't be overridden if you are configuring an organization's runner group that was shared by an enterprise. If you specify what workflow can access the runner group, you must use the full path to the workflow, including the repository name and owner, and you must pin the workflow to a branch, tag, or full SHA. For example: octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main.

    Only jobs directly defined within the selected workflows will have access to the runner group. Organization-owned runner groups cannot access workflows from a different organization in the enterprise; instead, you must create an enterprise-owned runner group.

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

Creating a runner group for an enterprise

Warning: If you are using a Fixed IP range, we recommend that you only use larger runners with private repositories. Forks of your repository can potentially run dangerous code on your larger runner by creating a pull request that executes the code in a workflow.

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

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.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

  2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

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

  4. Under " Policies", click Actions.

  5. Click the Runner groups tab.

  6. Click New runner group.

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

  8. 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

  9. Assign a policy for workflow access.

    You can configure a runner group to be accessible to a specific list of workflows, or to all workflows. This setting can't be overridden if you are configuring an organization's runner group that was shared by an enterprise. If you specify what workflow can access the runner group, you must use the full path to the workflow, including the repository name and owner, and you must pin the workflow to a branch, tag, or full SHA. For example: octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main.

    Only jobs directly defined within the selected workflows will have access to the runner group.

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

Using unique names for runner groups

GitHub Actions requires that runner group names must be unique at the organization level. This means that an organization will no longer be able to create a runner group with the same name as one in the enterprise. In addition, users will see a warning banner on any runner groups that share the same name as a group in the enterprise, suggesting that the organization group should be renamed.

To avoid ambiguity, a workflow will fail if there are duplicate runner groups in the organization and enterprise. To address this, you can either rename one of your runner groups in the organization or enterprise, or you can update your workflow file to add a prefix to the runner group name:

  • org/ or organization/
  • ent/ or enterprise/

Example: Using prefixes to differentiate runner groups

For example, if you have a runner group named my-group in the organization and another named my-group in the enterprise, you can update your workflow file to use org/my-group or ent/my-group to differentiate between the two.

Using org/:

runs-on:
  group: org/my-group
  labels: [ self-hosted, label-1 ]

Using ent/:

runs-on:
  group: ent/my-group
  labels: [ self-hosted, label-1 ]

Changing the access policy of a runner group

Warning: If you are using a Fixed IP range, we recommend that you only use larger runners with private repositories. Forks of your repository can potentially run dangerous code on your larger runner by creating a pull request that executes the code in a workflow.

For runner groups in an enterprise, you can change what organizations in the enterprise can access a runner group or restrict what workflows a runner group can run. For runner groups in an organization, you can change what repositories in the organization can access a runner group or restrict what workflows a runner group can run.

Changing what organizations or repositories can access a runner group

  1. Navigate to where your 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.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

      2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

  2. Navigate to the "Runner groups" settings:

    • In an organization:

      1. In the left sidebar, click Actions, then click Runner groups.
    • 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, click the runner group you'd like to configure.

  4. For runner groups in an enterprise, under Organization access, modify what organizations can access the runner group. For runner groups in an organization, under Repository access, modify what repositories can access the runner group.

Changing what workflows can access a runner group

You can configure a runner group to run either selected workflows or all workflows. For example, you might use this setting to protect secrets that are stored on runners or to standardize deployment workflows by restricting a runner group to run only a specific reusable workflow. This setting cannot be overridden if you are configuring an organization's runner group that was shared by an enterprise.

  1. Navigate to where your 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.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

      2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

  2. Navigate to the "Runner groups" settings:

    • In an organization:

      1. In the left sidebar, click Actions, then click Runner groups.
    • 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, click the runner group you'd like to configure.

  4. Under Workflow access, select the dropdown menu and click Selected workflows.

  5. Click .

  6. Enter a comma separated list of the workflows that can access the runner group. Use the full path, including the repository name and owner. Pin the workflow to a branch, tag, or full SHA. For example: octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main.

    Only jobs directly defined within the selected workflows will have access to the runner group.

    Organization-owned runner groups cannot access workflows from a different organization in the enterprise; instead, you must create an enterprise-owned runner group.

  7. Click Save.

Changing the name of a runner group

  1. Navigate to where your 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.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

      2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

  2. Navigate to the "Runner groups" settings:

    • In an organization:

      1. In the left sidebar, click Actions, then click Runner groups.
    • 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, click the runner group you'd like to configure.

  4. Change the runner group name.

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 where your 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.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

      2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

  2. Navigate to the GitHub Actions settings:

    • In an organization:

      1. In the left sidebar, click Actions, then 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 "Runners" list, click the runner that you want to configure.

  4. Select the Runner group drop-down.

  5. 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 where your 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.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

      2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

  2. Navigate to the "Runner groups" settings:

    • In an organization:

      1. In the left sidebar, click Actions, then click Runner groups.
    • 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. 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.