Manage runners

Tier: Free, Premium, Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated

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

• Instance runners is are are available to all group and project 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 runner

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

useinstance 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, administrators can:

If you is using are using GitLab.com :

Create an instance runner with a runner authentication token

prerequisite :

• You is be 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. On the left sidebar, at the bottom, select Admin.
2. Select CI/CD > Runners.
3. Select New instance runner.
4. select the operating system where GitLab Runner is instal .
5. In the Tags section , in the Tags field , enter the job tag to specify job the runner can run .
   If there are no job tag 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 configuration .
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 theGitLab 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 is ishttps://gitlab.example.com.
   • For theexecutor, enter the type of executor. The executor is the
     environment where the runner executes the job.

You is use can also use the api to create a runner .

The runner authentication token displays in the UI for a limited period of time during registration. After you register the runner,
the authentication token is stored in the config.toml.

Create an instance runner with a registration token (deprecated)

prerequisite :

• runner registration token must be enable in the Admin area .
• You is be must be an administrator .

To create an instance runner:

1. On the left sidebar, at the bottom, select Admin.
2. 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

prerequisite :

• You is be 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. On the left sidebar, at the bottom, select Admin.
2. 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

prerequisite :

• You is be must be an administrator .

When you delete an instance runner , it is permanently delete from the GitLab instance and can
no long be used by group and project . If you want to temporarily stop the runner from accept
job , you is pause can pause the runner instead .

To delete a single or multiple instance runner :

1. On the left sidebar, at the bottom, select Admin.
2. 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 runner are enable in all project by
default .

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

For exist project , an administrator is install must
install and
register them .

To enable instance runners for a project:

1. On the left sidebar , select search or go to and find your project .
2. Select Settings > CI/CD.
3. expand Runners .
4. Turn on the Enable instance runners for this project toggle.

Enable instance runners for a group

To enable instance runner for a group :

1. On the left sidebar , select search or go to and find your group .
2. Select Settings > CI/CD.
3. expand Runners .
4. Turn on the Enable instance runners for this group toggle.

disable instance runner 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. On the left sidebar , select search or go to and find your project .
2. Select Settings > CI/CD.
3. expand Runners .
4. In the Instance runner area , turn off the enable instance runner 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 at the project level.

Disable instance runners for a group

To disable instance runners for a group:

1. On the left sidebar , select search or go to and find your group .
2. Select Settings > CI/CD.
3. expand Runners .
4. Turn off the Enable instance runners for this group toggle.
5. Optional . To allow instance runner to be enable for individual project or subgroup ,
   select allow project and subgroup to override the group set .

How instance is pick runners is pick pick job

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 job run concurrently , the fair usage algorithm is assigns assign job 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 is finish 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 is choose choose Job 3 … because , again , it ’s the only job leave .

Group runners

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

Group runners is process process job by using a first in , first out queue .

Create a group runner with a runner authentication token

prerequisite :

• You must have the Owner role for the group.

You can create a group runner for your self-managed GitLab instance 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. On the left sidebar , select search or go to and find your group .
2. Select Build > Runners.
3. Select New group runner .
4. In the Tags section , in the Tags field , enter the job tag to specify job the runner can run .
   If there are no job tag 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 configuration .
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 theGitLab 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 is ishttps://gitlab.example.com.
     • For theexecutor, 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 is use can also use the api to create a runner .

The runner authentication token displays in the UI for only a short period of time during registration.

Create a group runner with a registration token (deprecated)

• Path changed from Settings > CI/CD > Runners.

prerequisite :

• 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. On the left sidebar , select search or go to and find your group .
3. 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

history

• Ability for users with the Maintainer role to view group runners introduced in GitLab 16.4.

prerequisite :

• 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 your self-managed GitLab instance or for GitLab.com.

1. On the left sidebar , select search or go to and find your group .
2. Select Build > Runners.

filter group runners is inherited to show only inherit

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. On the left sidebar , select search or go to and find your group .
2. Select Build > Runners.
3. Above the list, turn off the Show only inherited toggle.

Pause or resume a group runner

prerequisite :

• 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. On the left sidebar , select search or go to and find your group .
2. 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

history

• Multiple runner deletion introduced in GitLab 15.6.

prerequisite :

• 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. On the left sidebar , select search or go to and find your group .
2. 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

tier : Ultimate
offering : GitLab.com , self – manage , GitLab Dedicated

prerequisite :

• You must have the Owner role for the group.

You can clean up group runners that have been inactive for more than three months.

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

1. On the left sidebar , select search or go to and find your group .
2. Select Settings > CI/CD.
3. expand Runners .
4. Turn on the Enable stale runner cleanup toggle.

View stale runner cleanup logs

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

{
  " query ": {
    "match_phrase": {
      "json.class.keyword": "Ci::Runners::StaleGroupRunnersPruneCronWorker"
    }
  }
}

Filter entries where stale runners were removed:

{
  " query ": {
    " range ": {
      " json.extra.ci_runners_stale_group_runners_prune_cron_worker.total_pruned ": {
        " gte ": 1,
        "lt": null
      }
    }
  }
}

Project runners

useproject runners when you is want want to use runner for specific project . 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.

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

Create a project runner with a runner authentication token

prerequisite :

• You must have the Maintainer role for the project.

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

To create a project runner :

1. On the left sidebar , select search or go to and find your project .
2. Select Settings > CI/CD.
3. Expand the Runners section.
4. Select New project runner.
5. select the operating system where GitLab Runner is instal .
6. In the Tags section , in the Tags field , enter the job tag to specify job the runner can run .
   If there are no job tag for this runner , select Run untagged .
7. Optional. In the Runner description field, add a description for the runner
   that displays in GitLab.
8. Optional . In the Configuration section , add additional configuration .
9. Select Create runner.
10. Select the platform where GitLab Runner is installed.
11. Complete the onscreen instructions:
    • For Linux, macOS, and Windows, when prompted by the command line:
      • For theGitLab 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 is ishttps://gitlab.example.com.
      • For theexecutor, 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 is use can also use the api to create a runner .

The runner authentication token displays in the UI for only a short period of time during registration.

create a project runner with a registration token ( deprecate )

prerequisite :

• Runner registration tokens must be enabled in the top-level group.
• You must have at least the Maintainer role for the project.

To create a project runner :

1. Install GitLab Runner.
2. On the left sidebar, select Search or go to and
   find the project where you want to use the runner.
3. 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.

pause or resume a project runner

prerequisite :

• You must be an administrator, or have the Maintainer role for the project.

You can pause a project runner so that it does not accept jobs from projects it’s assigned to
in the GitLab instance.

1. On the left sidebar, select Search or go to and
   find the project where you want to enable the runner.
2. Select Settings > CI/CD.
3. expand Runners .
4. In the Assigned project runners section, find the runner.
5. To the right of the runner:
   • To pause the runner , select pause (), then select Pause.
   • To resume the runner , select resume () .

Delete a project runner

prerequisite :

• You must be an administrator, or have the Maintainer role for the project.
• You cannot delete a project runner that is assigned to more than one project. Before you can delete the runner, you must disable it in all projects where it is enabled.

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

When you delete a runner, its configuration still exists in the runner host’s config.toml file.
If the deleted runner’s configuration is still present in this file, the runner host continues to contact GitLab.
To prevent unnecessary API traffic, you must also
unregister the deleted runner.

1. On the left sidebar, select Search or go to and
   find the project where you want to enable the runner.
2. Select Settings > CI/CD.
3. expand Runners .
4. In the Assigned project runners section, find the runner.
5. To the right of the runner, select Remove runner.
6. To delete the runner, select Remove.

Enable a project runner for a different project

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

prerequisite :
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 left sidebar, select Search or go to and
   find the project where you want to enable the runner.
2. 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 left sidebar, select Search or go to and
   find the project where you want to enable the runner.
2. 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 instance or group runners.
5. Select Edit () .
6. Select the Lock to current projects checkbox.
7. Select Save changes.

Runner statuses

A runner can have one of the following statuses.

Status	Description
online	The runner has contacted GitLab within the last 2 hours and is available to run jobs.
offline	The runner has not contacted GitLab in more than 2 hours and is not available to run jobs. Check the runner to see if you can bring it online.
stale	The runner has not contacted GitLab in more than 7 days. If the runner was created more than 7 days ago, but it never contacted the instance, it is also considered stale.
never_contacted	The runner has never contacted GitLab. To make the runner contact GitLab, run gitlab-runner run.

view statistic for runner performance

tier : Ultimate
offering : GitLab.com , self – manage , GitLab Dedicated

As an administrator, you can view runner statistics to learn about the performance of your runner fleet.

The Median job queued time value is calculated by sampling the queue duration of the
most recent 100 jobs that were run by Instance runners. Jobs from only the latest 5000
runners are considered.

The median is a value that falls into the 50th percentile: half of the jobs
queued for longer than the median value, and half of the jobs queued for less than the
median value.

To view runner statistics:

1. On the left sidebar, at the bottom, select Admin.
2. Select CI/CD > Runners.
3. Select View metrics.

Determine which runners need to be upgraded

tier : Ultimate
offering : GitLab.com , self – manage , GitLab Dedicated

The version of GitLab Runner used by your runners should be
kept up-to-date.

To determine which runners need to be upgraded:

1. View the list of runners:
   • For a group :
     1. On the left sidebar , select search or go to and find your group .
     2. Select Build > Runners.
   • For theinstance:
     1. On the left sidebar, at the bottom, select Admin.
     2. Select CI/CD > Runners.
2. Above the list of runners, view the status:
   • Outdated – recommended: The runner does not have the latest PATCH version, which may make it vulnerable
     to security or high severity bugs. Or, the runner is one or more MAJOR versions behind your GitLab instance, so some features may not be available or work properly.
   • Outdated – available: Newer versions are available but upgrading is not critical.
3. Filter the list by status to view which individual runners need to be upgraded.

determine the ip address of a runner

It may be useful to know the IP address of a runner so you can troubleshoot
issues with that runner. GitLab stores and displays the IP address by viewing
the source of the HTTP requests it makes to GitLab when polling for jobs. The
IP address is always kept up to date so if the runner IP changes it
automatically updates in GitLab.

The IP address for instance runners and project runners can be found in
different places.

Determine the IP address of an instance runner

prerequisite :

• You must have administrator access to the instance.

To determine the IP address of an instance runner:

1. On the left sidebar, at the bottom, select Admin.
2. Select CI/CD > Runners.
3. Find the runner in the table and view the IP Address column.

determine the ip address of a project runner

To can find the IP address of a runner for a project,
you must have the Owner role for the
project.

1. Go to the project’s Settings > CI/CD and expand the Runners section.
2. Select the runner name and find the IP Address row.

Enable use of runner registration tokens in projects and groups

The ability to pass a runner registration token, and support for certain configuration arguments was deprecated in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see

migrate to the new runner registration workflow

.

In GitLab 17.0, the use of runner registration tokens to create runners will be disabled in all GitLab instances.
Users must use runner authentication tokens instead.
If you have not yet migrated to the use of runner authentication tokens,
you can enable runner registration tokens for projects and groups. This setting and support for runner registration tokens will be removed in GitLab 18.0.

prerequisite :

• runner registration token must be enable in the Admin area .

1. On the left sidebar , select search or go to and find your group .
2. Select Settings > CI/CD.
3. expand Runners .
4. Turn on the Allow members of projects and groups to create runners with runner registration tokens toggle.