Manage runners

GitLab Runner has the following types of runners, which are available based on who you want to have access:

• Instance 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.

Instance runners

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

Use instance 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 GitLab Self-Managed, administrators can:

• Install GitLab Runner and register an instance runner.
• Configure a maximum number of instance runner compute minutes for each group.

If you are using GitLab.com:

• You can select from a list of instance runners that GitLab maintains.
• The instance runners consume the compute minutes included with your account.

Create an instance runner with a runner authentication token

Prerequisites:

• You must be an administrator.

When you create a runner, it is assigned a runner authentication token that you use to register it. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue.

To create an instance runner:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select CI/CD > Runners.
3. Select Create instance runner.
4. Select the operating system where GitLab Runner is installed.
5. In the Tags section, in the Tags field, enter the job tags to specify jobs the runner can run. If there are no job tags for this runner, select Run untagged.
6. Optional. In the Runner description field, to add a runner description that displays in GitLab, enter a runner description.
7. Optional. In the Configuration section, add additional configurations.
8. Select Create runner.
9. Follow the on-screen instructions to register the runner from the command line. When prompted by the command line:
   • For the GitLab instance URL, use the URL for your GitLab instance. For example, if your project is hosted on gitlab.example.com/yourname/yourproject, your GitLab instance URL is https://gitlab.example.com.
   • For the executor, enter the type of executor. The executor is the environment where the runner executes the job.

You can also use the API to create a runner.

Create an instance runner with a registration token (deprecated)

Prerequisites:

• Runner registration tokens must be enabled in the Admin area.
• You must be an administrator.

To create an instance runner:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select CI/CD > Runners.
3. Select Register an instance runner.
4. Copy the registration token.
5. Register the runner.

Pause or resume an instance runner

Prerequisites:

• You must be an administrator.

You can pause a runner so that it does not accept jobs from groups and projects in the GitLab instance.

1. In the upper-right corner, select Admin.
2. In the left sidebar, select CI/CD > Runners.
3. In the search box, enter the runner description or filter the runner list.
4. In the runner list, to the right of the runner:
   • To pause the runner, select Pause ( ).
   • To resume the runner, select Resume ( ).

Delete instance runners

Prerequisites:

• You must be an administrator.

When you delete an instance runner, it is permanently deleted from the GitLab instance and can no longer be used by groups and projects. If you want to temporarily stop the runner from accepting jobs, you can pause the runner instead.

To delete a single or multiple instance runners:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select CI/CD > Runners.
3. In the search box, enter the runner description or filter the list of runners.
4. Delete the instance runner:
   • To delete a single runner, next to the runner, select Delete runner ( ).
   • To delete multiple instance runners, select the checkbox for each runner and select Delete selected.
   • To delete all runners, select the checkbox at the top of the runner list and select Delete selected.
5. Select Permanently delete runner.

Enable instance runners for a project

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

On GitLab Self-Managed, an administrator can enable them for all new projects.

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

To enable instance runners for a project:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Runners.
4. Enable the Turn on instance runners for this project toggle.

Enable instance runners for a group

To enable instance runners for a group:

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Runners.
4. Enable the Turn on instance runners for this group toggle.

Disable instance runners for a project

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

To disable instance runners for a project:

1. In the top bar, select Search or go to and find your project.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Runners.
4. In the Instance runners area, turn off the Turn on runners for this project toggle.

Instance runners are automatically disabled for a project:

• If the instance runners setting for the parent group is disabled, and
• If overriding this setting is not permitted for projects.

Disable instance runners for a group

To disable instance runners for a group:

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Runners.
4. Turn off the Enable instance runners for this group toggle.
5. Optional. To allow instance runners to be enabled for individual projects or subgroups, select Allow projects and subgroups to override the group setting.

How instance runners pick jobs

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

The fair usage queue algorithm assigns jobs based on the projects that have the fewest number of jobs already running on instance 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, Job 3 is next 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. Job 1 finishes.
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. Job 4 finishes.
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. Finally, Job 3 is next because 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 queue.

Create a group runner with a runner authentication token

Prerequisites:

• You must have the Owner role for the group.

You can create a group runner for GitLab Self-Managed or for GitLab.com. When you create a runner, it is assigned a runner authentication token that you use to register it. The runner uses the token to authenticate with GitLab when it picks up jobs from the job queue.

To create a group runner:

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Build > Runners.
3. Select Create group runner.
4. In the Tags section, in the Tags field, enter the job tags to specify jobs the runner can run. If there are no job tags for this runner, select Run untagged.
5. Optional. In the Runner description field, add a runner description that displays in GitLab.
6. Optional. In the Configuration section, add additional configurations.
7. Select Create runner.
8. Select the platform where GitLab Runner is installed.
9. Complete the onscreen instructions:
   • For Linux, macOS, and Windows, when prompted by the command line:
     • For the GitLab instance URL, use the URL for your GitLab instance. For example, if your project is hosted on gitlab.example.com/yourname/yourproject, your GitLab instance URL is https://gitlab.example.com.
     • For the executor, enter the type of executor. The executor is the environment where the runner executes the job.
   • For Google Cloud, see Provisioning runners in Google Cloud.

You can also use the API to create a runner.

Create a group runner with a registration token (deprecated)

Prerequisites:

• Runner registration tokens must be enabled in the top-level group.
• You must have the Owner role for the group.

To create a group runner:

1. Install GitLab Runner.
2. In the top bar, select Search or go to and find your group.
3. In the left sidebar, select Build > 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 group runners

Prerequisites:

• You must have the Maintainer or Owner role for the group.

You can view all runners for a group and its subgroups and projects. You can do this for GitLab Self-Managed or for GitLab.com.

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Build > Runners.

Filter group runners to show only inherited

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 instance runners and those in other groups:

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Build > Runners.
3. Above the list, turn off the Show only inherited toggle.

Pause or resume a group runner

Prerequisites:

• You must be an administrator or have the Owner role for the group.

You can pause a runner so that it does not accept jobs from subgroups and projects in the GitLab instance. If you pause a group runner that is used by multiple projects, the runner pauses for all projects.

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Build > Runners.
3. In the search box, enter the runner description or filter the runner list.
4. In the runner list, to the right of the runner:
   • To pause the runner, select Pause ( ).
   • To resume the runner, select Resume ( ).

Delete a group runner

Prerequisites:

• You must be an administrator or have the Owner role for the group.

When you delete a group runner, it is permanently deleted from the GitLab instance and can no longer be used by subgroups and projects. If you want to temporarily stop the runner from accepting jobs, you can pause the runner instead.

To delete a single or multiple group runners:

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Build > Runners.
3. In the search box, enter the runner description or filter the list of runners.
4. Delete the group runner:
   • To delete a single runner, next to the runner, select Delete runner ( ).
   • To delete multiple instance runners, select the checkbox for each runner and select Delete selected.
   • To delete all runners, select the checkbox at the top of the runner list and select Delete selected.
5. Select Permanently delete runner.

Clean up stale group runners

Prerequisites:

• You must have the Owner role for the group.

You can clean up group runners that have been inactive for more than seven days.

Group runners are those that were created in a specific group.

1. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Runners.
4. Turn on the Enable stale runner cleanup toggle.

View stale runner cleanup logs

You can check the Sidekiq logs to see the cleanup result. In Kibana you can use the following query:

{