Skip to main content

Using larger runners

GitHub offers larger runners with more RAM and CPU.

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.

Overview of larger runners

In addition to the standard GitHub-hosted runners, GitHub also offers customers on GitHub Team and GitHub Enterprise Cloud plans a range of larger runners with more RAM and CPU. These runners are hosted by GitHub and have the runner application and other tools preinstalled.

When you add a larger runner to an organization, you are defining a type of machine from a selection of available hardware specifications and operating system images. GitHub will then create multiple instances of this runner that scale up and down to match the job demands of your organization, based on the autoscaling limits you define.

Architectural overview of larger runners

The larger runners are managed at the organization level, where they are arranged into groups that can contain multiple instances of the runner. They can also be created at the enterprise level and shared with organizations in the hierarchy. Once you've created a group, you can then add a runner to the group and update your workflows to target the label assigned to the larger runner. You can also control which repositories are permitted to send jobs to the group for processing. For more information about groups, see "Controlling access to larger runners."

In the following diagram, a class of hosted runner named ubuntu-20.04-16core has been defined with customized hardware and operating system configuration.

Diagram explaining larger runner

  1. Instances of this runner are automatically created and added to a group called ubuntu-20.04-16core.
  2. The runners have been assigned the label ubuntu-20.04-16core.
  3. Workflow jobs use the ubuntu-20.04-16core label in their runs-on key to indicate the type of runner they need to execute the job.
  4. GitHub Actions checks the runner group to see if your repository is authorized to send jobs to the runner.
  5. The job runs on the next available instance of the ubuntu-20.04-16core runner.

Autoscaling larger runners

Your larger runners can be configured to automatically scale to suit your needs. When jobs are submitted for processing, more machines can be automatically provisioned to run the jobs, until reaching a pre-defined maximum limit. Each machine only handles one job at a time, so these settings effectively determine the number of jobs that can be run concurrently.

During the runner deployment process, you can configure the Max option, which allows you to control your costs by setting the maximum parallel number of machines that are created in this set. A higher value here can help avoid workflows being blocked due to parallelism.

Networking for larger runners

By default, larger runners receive a dynamic IP address that changes for each job run. Optionally, GitHub Enterprise Cloud customers can configure their larger runners to receive a static IP address from GitHub's IP address pool. When enabled, instances of the larger runner will receive an address from a range that is unique to the runner, allowing you to use this range to configure a firewall allowlist. You can use up to 10 static IP address ranges in total across all your larger runners.

Note: If runners are unused for more than 30 days, their IP address ranges are automatically removed and cannot be recovered.

Planning for larger runners

Create a runner group

Runner groups are used to collect sets of virtual machines and create a security boundary around them. You can then decide which organizations or repositories are permitted to run jobs on those sets of machines. During the larger runner deployment process, the runner can be added to an existing group, or otherwise it will join a default group. You can create a group by following the steps in "Controlling access to larger runners."

Understanding billing

Note: The larger runners do not use included entitlement minutes, and are not free for public repositories.

Compared to standard GitHub-hosted runners, larger runners are billed differently. For more information, see "Per-minute rates".

Adding a larger runner to an enterprise

You can add larger runners to an enterprise, where they can be assigned to multiple organizations. The organization admins can then control which repositories can use the runners. To add a larger runner to an enterprise, you must be an enterprise owner.

You can choose an operating system and a hardware configuration from the list of available options. When new instances of this runner are deployed through autoscaling, they'll use the same operating system and hardware configuration you've defined here.

You can also define the labels that identify the runner, which is how your workflows will be able to send jobs to the runners for processing (using runs-on). New runners are automatically assigned to the default group, or you can choose which group the runners must join during the runner creation process. In addition, you can modify the runner's group membership after you've registered the runner. For more information, see "Controlling access to larger runners."

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

  2. Under " Policies", click Actions.

  3. Click the Runners tab.

  4. Click New runner, then click New Github-hosted runner.

  5. Complete the required details to configure your new runner:

    • Name: Enter a name for your new runner. For easier identification, this should indicate its hardware and operating configuration, such as ubuntu-20.04-16core.
    • Runner image: Choose an operating system from the available options. Once you've selected an operating system, you will be able to choose a specific version.
    • Runner size: Choose a hardware configuration from the drop-down list of available options.
    • Auto-scaling: Choose the maximum number of runners that can be active at any time.
    • Runner group: Choose the group that your runner will be a member of. This group will host multiple instances of your runner, as they scale up and down to suit demand.
    • Networking: Only for GitHub Enterprise Cloud: Choose whether a static IP address range will be assigned to instances of the larger runner. You can use up to 10 static IP addresses in total.
  6. Click Create runner.

  7. To allow organizations to access your larger runners, you specify the list of organizations that can use it. For more information, see "Managing access to your runners."

Adding a larger runner to an organization

You can add a larger runner to an organization, where the organization admins can control which repositories can use it.

You can choose an operating system and a hardware configuration from the list of available options. When new instances of this runner are deployed through autoscaling, they'll use the same operating system and hardware configuration you've defined here.

You can also define the labels that identify the runner, which is how your workflows will be able to send jobs to the runners for processing (using runs-on). New runners are automatically assigned to the default group, or you can choose which group the runners must join during the runner creation process. In addition, you can modify the runner's group membership after you've registered the runner. For more information, see "Controlling access to larger runners."

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

  4. Click New runner, then click New Github-hosted runner.

  5. Complete the required details to configure your new runner:

    • Name: Enter a name for your new runner. For easier identification, this should indicate its hardware and operating configuration, such as ubuntu-20.04-16core.
    • Runner image: Choose an operating system from the available options. Once you've selected an operating system, you will be able to choose a specific version.
    • Runner size: Choose a hardware configuration from the drop-down list of available options.
    • Auto-scaling: Choose the maximum number of runners that can be active at any time.
    • Runner group: Choose the group that your runner will be a member of. This group will host multiple instances of your runner, as they scale up and down to suit demand.
    • Networking: Only for GitHub Enterprise Cloud: Choose whether a static IP address range will be assigned to instances of the larger runner. You can use up to 10 static IP addresses in total.
  6. Click Create runner.

  7. To allow repositories to access your larger runners, add them to the list of repositories that can use it. For more information, see "Managing access to your runners."

Running jobs on your runner

Once your runner type has been defined, you can update your workflow YAML files to send jobs to your newly created runner instances for processing. In this example, a runner group is populated with Ubuntu 16-core runners, which have been assigned the label ubuntu-20.04-16core. If you have a runner matching this label, the check-bats-version job then uses the runs-on key to target that runner whenever the job is run:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

To find out which runners are enabled for your repository and organization, you must contact your organization admin. Your organization admin can create new runners and runner groups, as well as configure permissions to specify which repositories can access a runner group.

Managing access to your runners

Note: Before your workflows can send jobs to larger runners, you must first configure permissions for the runner group. See the following sections for more information.

Runner groups are used to control which repositories can run jobs on your larger runners. You must grant access to the group from each level of the management hierarchy, depending on where you've defined the larger runner:

  • Runners at the enterprise level: Configure the runner group to grant access to all the required organizations. In addition, for each organization, you must configure the group to specify which repositories are allowed access.
  • Runners at the organization level: Configure the runner group by specifying which repositories are allowed access.

For example, the following diagram has a runner group named grp-ubuntu-20.04-16core at the enterprise level. Before the repository named octo-repo can use the runners in the group, you must first configure the group at the enterprise level to allow access from the octo-org organization; you must then configure the group at the organization level to allow access from octo-repo:

Diagram explaining larger runner groups

Allowing repositories to access a runner group

This procedure demonstrates how to configure group permissions at the enterprise and organization levels:

  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.

  • For runner groups in an enterprise: under Organization access, modify which organizations can access the runner group.
  • For runner groups in an organization: under Repository access, modify which repositories can access the runner group.

Warning:

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.
  • You could incur unexpected costs if you allow forked repositories to run jobs on your larger runners.

For more information, see "Controlling access to larger runners."