How do I delete/unregister a GitLab runner

1. List runners to get their tokens and URLs:

   sudo gitlab-runner list
   

2. Verify with delete option specifying runner's token and URL:

   sudo gitlab-runner verify --delete -t YMsSCHnjGssdmz1JRoxx -u http://git.xxxx.com/
   

Get your runner token and id

First, go to the GitLab settings page and find the token (e.g. 250cff81 in the image below) and the id (e.g. 354472 in the image below) of the GitLab runner which you wish to delete.

Use the gitlab-runner CLI to unregister the runner

If you have access to the machine which was used to register the GitLab runner, you can unregister the runner using the following command, where you replace {TOKEN} with the token of your GitLab runner (e.g. 250cff81 in the example above).

gitlab-runner unregister --url https://gitlab.org/ --token {TOKEN}

Use the GitLab API to unregister the runner

If you no longer have access to the machine which was used to register the runner, or if the runner is associated with multiple projects, you can use the following Python script. Set RUNNER_ID to the id of your runner (e.g. 354472 in the example above) and GITLAB_AUTH_TOKEN to a GitLab token which you can generate from your profile page.

import os
import requests

GITLAB_AUTH_TOKEN = ...
RUNNER_ID = ...

headers = {"PRIVATE-TOKEN": GITLAB_AUTH_TOKEN}

r = requests.get(f"https://gitlab.com/api/v4/runners/{RUNNER_ID}", headers=headers)
runner_data = r.json()

for project in runner_data.get("projects", []):
    r = requests.delete(
        f"https://gitlab.com/api/v4/projects/{project['id']}/runners/{RUNNER_ID}",
        headers=headers,
    )
    if not r.ok:
        print("Encountered an error deleting runner from project:", r.json())

r = requests.delete(f"https://gitlab.com/api/v4/runners/{RUNNER_ID}", headers=headers)
if not r.ok:
    print("Encountered an error deleting runner:", r.json())

Here's one-liner to remove offline runners (for GitLab 14.5):

curl --header "PRIVATE-TOKEN: <private_token>" "https://<your-instance-address>/api/v4/runners/all?scope=offline&per_page=100" | jq '.[].id' | xargs -I runner_id curl --request DELETE --header "PRIVATE-TOKEN: <private_token>" "https://<your-instance-address>/api/v4/runners/runner_id"

You might run this more than once if you have more than 100 offline runners (per_page=100).

If you no longer have enough information related to a runner, GitLab (UI) will only allow you to disable it.

However, there is a workaround to delete runners via the GitLab UI (if you lost your info).

1. Create a new blank project within GitLab (called dummy, for instance)
2. Go to the CI/CD settings page (Settings -> CI/CD -> Runners)
3. Enable all runners you want to delete to be able to edit them
4. Lock every runner you wish to delete to the dummy project as shown below

5. Delete the dummy project

The runners are gone.

The overall idea was to lock all of the orphan runners to a dummy project, then delete that dummy.

PS: If runners are not visible in the dummy project, you may want to unlock them from the project they are associated with, then do the procedure again.

EDIT: This process is most particularly useful when

• You do not have access to the machine host (especially in big organisations where rights are segmented), only to your GitLab instance.

• You think that creating a runner via the UI should also give you the ability to delete a runner via the UI

• You have enough rights but you don't want to fire up a Ruby instance (like described in the GitLab doc) to delete a runner.

If you are talking about the runners listed in "Available group runners: ...", they can be deleted at the runner settings page of your group.

If you've deleted the specific runner in your gitlab server, try to remove the unused runner through config.toml file (locally).

To show all runners: $ gitlab-runner list

Or $cat /Users/yourUser/.gitlab-runner/config.toml

If you try to delete a runner with this command:

$ gitlab-runner verify --delete -t Token-From-Your-Runner -u https://gitlab.com/ 

-> You'll have an error (Verifying runner... error) 'cause the process doesn't not match with your remote runner...

Then (To solve this trouble) Delete all runners by the name with their indentation! If you only have one, the file shows as:

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]