The scope of runners

Runners are available based on who you want to have access:

  • Shared runners are available to all groups and projects in a GitLab instance.
  • Group runners are available to all projects and subgroups in a group.
  • Project runners are associated with specific projects. Typically, project runners are used by one project at a time.

Shared runners

Shared runners are available to every project in a GitLab instance.

Use shared runners when you have multiple jobs with similar requirements. Rather than having multiple runners idling for many projects, you can have a few runners that handle multiple projects.

If you are using a self-managed instance of GitLab:

  • Your administrator can install and register shared runners by going to your project’s Settings > CI/CD, expanding Runners, and selecting Show runner installation instructions. These instructions are also available in the documentation.
  • The administrator can also configure a maximum number of shared runner CI/CD minutes for each group.

If you are using GitLab.com:

Enable shared runners for a project

On GitLab.com, shared runners are enabled in all projects by default.

On self-managed instances of GitLab, an administrator can enable them for all new projects.

For existing projects, an administrator must install and register them.

To enable shared runners for a project:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.
  4. Turn on the Enable shared runners for this project toggle.

Enable shared runners for a group

To enable shared runners for a group:

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.
  4. Turn on the Enable shared runners for this group toggle.

Disable shared runners for a project

You can disable shared runners for individual projects or for groups. You must have the Owner role for the project or group.

To disable shared runners for a project:

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.
  4. In the Shared runners area, turn off the Enable shared runners for this project toggle.

Shared runners are automatically disabled for a project:

  • If the shared runners setting for the parent group is disabled, and
  • If overriding this setting is not permitted at the project level.

Disable shared runners for a group

To disable shared runners for a group:

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.
  4. Turn off the Enable shared runners for this group toggle.
  5. Optional. To allow shared runners to be enabled for individual projects or subgroups, select Allow projects and subgroups to override the group setting.
note
To re-enable the shared runners for a group, turn on the Enable shared runners for this group toggle. Then, a user with the Owner or Maintainer role must explicitly change this setting for each project subgroup or project.

How shared runners pick jobs

Shared runners process jobs by using a fair usage queue. This queue prevents projects from creating hundreds of jobs and using all available shared runner resources.

The fair usage queue algorithm assigns jobs based on the projects that have the fewest number of jobs already running on shared runners.

For example, if these jobs are in the queue:

  • Job 1 for Project 1
  • Job 2 for Project 1
  • Job 3 for Project 1
  • Job 4 for Project 2
  • Job 5 for Project 2
  • Job 6 for Project 3

When several CI/CD jobs run concurrently, the fair usage algorithm assigns jobs in this order:

  1. Job 1 is first, because it has the lowest job number from projects with no running jobs (that is, all projects).
  2. Job 4 is next, because 4 is now the lowest job number from projects with no running jobs (Project 1 has a job running).
  3. Job 6 is next, because 6 is now the lowest job number from projects with no running jobs (Projects 1 and 2 have jobs running).
  4. Job 2 is next, because, of projects with the lowest number of jobs running (each has 1), it is the lowest job number.
  5. Job 5 is next, because Project 1 now has 2 jobs running and Job 5 is the lowest remaining job number between Projects 2 and 3.
  6. Finally is Job 3… because it’s the only job left.

When only one job runs at a time, the fair usage algorithm assigns jobs in this order:

  1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects).
  2. We finish Job 1.
  3. Job 2 is next, because, having finished Job 1, all projects have 0 jobs running again, and 2 is the lowest available job number.
  4. Job 4 is next, because with Project 1 running a Job, 4 is the lowest number from projects running no jobs (Projects 2 and 3).
  5. We finish Job 4.
  6. Job 5 is next, because having finished Job 4, Project 2 has no jobs running again.
  7. Job 6 is next, because Project 3 is the only project left with no running jobs.
  8. Lastly we choose Job 3… because, again, it’s the only job left.

Group runners

Use group runners when you want all projects in a group to have access to a set of runners.

Group runners process jobs by using a first in, first out (FIFO) queue.

Create a group runner

Introduced in GitLab 14.10, path changed from Settings > CI/CD > Runners.

You can create a group runner for your self-managed GitLab instance or for GitLab.com. You must have the Owner role for the group.

To create a group runner:

  1. Install GitLab Runner.
  2. On the top bar, select Main menu > Groups and find your group.
  3. On the left sidebar, select CI/CD > Runners.
  4. In the upper-right corner, select Register a group runner.
  5. Select Show runner installation and registration instructions. These instructions include the token, URL, and a command to register a runner.

Alternately, you can copy the registration token and follow the documentation for how to register a runner.

View and manage group runners

Introduced in GitLab 13.2.

You can view and manage all runners for a group, its subgroups, and projects. You can do this for your self-managed GitLab instance or for GitLab.com. You must have the Owner role for the group.

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select CI/CD > Runners.

From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects.

Delete multiple group runners

Introduced in GitLab 15.6

Prerequisites:

  • You must have either:
    • Owner role for the group.
    • Access to delete any runners in the group.

To delete multiple runners in a single action in the group list:

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select CI/CD > Runners.
  3. To delete multiple runners, you can either:
    • Select the checkbox next to the runner.
    • Select the checkbox at the top of the runner list to select all runners in the list.
  4. To delete the runners, select Delete selected.

Filter group runners to show only inherited

Version history

You can choose to show all runners in the list, or show only those that are inherited from the instance or other groups.

By default, only those that are inherited are shown.

To show all runners available in the instance, including shared runners and those in other groups:

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select CI/CD > Runners.
  3. Above the list, turn off the Show only inherited toggle.

Pause or remove a group runner

You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. You must have the Owner role for the group.

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select CI/CD > Runners.
  3. Select Pause or Remove runner.
    • If you pause a group runner that is used by multiple projects, the runner pauses for all projects.
    • From the group view, you cannot remove a runner that is assigned to more than one project. You must remove it from each project first.
  4. On the confirmation dialog, select OK.

Project runners

Use project runners when you want to use runners for specific projects. For example, when you have:

  • Jobs with specific requirements, like a deploy job that requires credentials.
  • Projects with a lot of CI activity that can benefit from being separate from other runners.

You can set up a project runner to be used by multiple projects. Project runners must be enabled for each project explicitly.

Project runners process jobs by using a first in, first out (FIFO) queue.

note
Project runners do not get shared with forked projects automatically. A fork does copy the CI/CD settings of the cloned repository.

Create a project runner

You can create a project runner for your self-managed GitLab instance or for GitLab.com.

Prerequisite:

  • You must have at least the Maintainer role for the project.

To create a project runner:

  1. Install GitLab Runner.
  2. On the top bar, select Main menu > Projects and find the project where you want to use the runner.
  3. On the left sidebar, select Settings > CI/CD.
  4. Expand Runners.
  5. In the Project runners section, note the URL and token.
  6. Register the runner.

The runner is now enabled for the project.

Enable a project runner for a different project

After a project runner is created, you can enable it for other projects.

Prerequisites: You must have at least the Maintainer role for:

  • The project where the runner is already enabled.
  • The project where you want to enable the runner.
  • The project runner must not be locked.

To enable a project runner for a project:

  1. On the top bar, select Main menu > Projects and find the project where you want to enable the runner.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.
  4. In the Project runners area, by the runner you want, select Enable for this project.

You can edit a project runner from any of the projects it’s enabled for. The modifications, which include unlocking and editing tags and the description, affect all projects that use the runner.

An administrator can enable the runner for multiple projects.

Prevent a project runner from being enabled for other projects

You can configure a project runner so it is “locked” and cannot be enabled for other projects. This setting can be enabled when you first register a runner, but can also be changed later.

To lock or unlock a project runner:

  1. On the top bar, select Main menu > Projects and find the project where you want to enable the runner.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.
  4. Find the project runner you want to lock or unlock. Make sure it’s enabled. You cannot lock shared or group runners.
  5. Select Edit ( ).
  6. Select the Lock to current projects checkbox.
  7. Select Save changes.