Runners API

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

This page describes endpoints for runners registered to an instance. To create a runner linked to the current user, see Create a runner.

Pagination is available on the following API endpoints (they return 20 items by default):

GET /runners
GET /runners/all
GET /runners/:id/jobs
GET /projects/:id/runners
GET /groups/:id/runners

Registration and authentication tokens

There are two tokens to take into account when connecting a runner with GitLab.

Token	Description
Registration token	Token used to register the runner. It can be obtained through GitLab.
Authentication token	Token used to authenticate the runner with the GitLab instance. The token is obtained automatically when you register a runner or by the Runners API when you manually register a runner or reset the authentication token. You can also obtain the token by using the `POST /user/runners` endpoint.

Here’s an example of how the two tokens are used in runner registration:

You register the runner via the GitLab API using a registration token, and an authentication token is returned.
You use that authentication token and add it to the runner’s configuration file:
```
[[runners]]
  token = "<authentication_token>"
```

GitLab and the runner are then connected.

List owned runners

Get a list of runners available to the user.

Prerequisites:

You must be an administrator of or have the Owner role for the target namespace or project.
For instance_type, you must be an administrator of the GitLab instance.

GET /runners
GET /runners?scope=active
GET /runners?type=project_type
GET /runners?status=online
GET /runners?paused=true
GET /runners?tag_list=tag1,tag2

Attribute	Type	Required	Description
`scope`	string	no	Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided
`type`	string	no	The type of runners to return, one of: `instance_type`, `group_type`, `project_type`
`status`	string	no	The status of runners to return, one of: `online`, `offline`, `stale`, or `never_contacted`. Other possible values are the deprecated `active` and `paused`. Requesting `offline` runners might also return `stale` runners because `stale` is included in `offline`.
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`tag_list`	string array	no	A list of runner tags
`version_prefix`	string	no	The prefix of the version of the runners to return. For example, `15.0`, `14`, `16.1.241`

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"

The active and paused values in the status query parameter were deprecated and will be removed in a future version of the REST API. They are replaced by the paused query parameter.

The active attribute in the response was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

The ip_address attribute in the response was deprecated in GitLab 16.1 and will be removed in a future version of the REST API. This attribute will start returning an empty string in GitLab 17.0. The ipAddress attribute can be found inside the respective runner manager, currently only available through the GraphQL CiRunnerManager type.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "online"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

List all runners

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

Get a list of all runners in the GitLab instance (project and shared). Access is restricted to users with administrator access.

Prerequisites:

You must be an administrator of or have the Owner role for the target namespace or project.
For instance_type, you must be an administrator of the GitLab instance.

GET /runners/all
GET /runners/all?scope=online
GET /runners/all?type=project_type
GET /runners/all?status=online
GET /runners/all?paused=true
GET /runners/all?tag_list=tag1,tag2

Attribute	Type	Required	Description
`scope`	string	no	Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `specific`, `shared`, `active`, `paused`, `online` and `offline`; showing all runners if none provided
`type`	string	no	The type of runners to return, one of: `instance_type`, `group_type`, `project_type`
`status`	string	no	The status of runners to return, one of: `online`, `offline`, `stale`, or `never_contacted`. Other possible values are the deprecated `active` and `paused`. Requesting `offline` runners might also return `stale` runners because `stale` is included in `offline`.
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`tag_list`	string array	no	A list of runner tags
`version_prefix`	string	no	The prefix of the version of the runners to return. For example, `15.0`, `16.1.241`

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"

The active and paused values in the status query parameter were deprecated and will be removed in a future version of the REST API. They are replaced by the paused query parameter.

The active attribute in the response was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-1",
        "id": 1,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    },
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-2",
        "id": 3,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "paused"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

To view more than the first 20 runners, use pagination.

Get runner’s details

Get details of a runner.

Instance-level runner details via this endpoint are available to all authenticated users.

Prerequisites:

You must have at least the Developer role for the target namespace or project.
An access token with the manage_runner scope and the appropriate role.

GET /runners/:id

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

The token attribute in the response was deprecated in GitLab 12.10 and removed in GitLab 13.0.

The active attribute in the response was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

The version, revision, platform, and architecture attributes in the response were deprecated in GitLab 17.0 and will be removed in a future version of the REST API. The same attributes can be found inside the respective runner manager, currently only available through the GraphQL CiRunnerManager type.

Example response:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "name": null,
    "online": true,
    "status": "online",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": 3600
}

Update runner’s details

Update details of a runner.

PUT /runners/:id

Prerequisites:

For instance_type, you must be an administrator of the GitLab instance.
For group_type, you must have the Owner role for the target namespace.
For project_type, you must have at least the Maintainer role for the target project.
An access token with the manage_runner scope and the appropriate role.

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner
`description`	string	no	The description of the runner
`active`	boolean	no	Deprecated: Use `paused` instead. Flag indicating whether the runner is allowed to receive jobs
`paused`	boolean	no	Specifies if the runner should ignore new jobs
`tag_list`	array	no	The list of tags for the runner
`run_untagged`	boolean	no	Specifies if the runner can execute untagged jobs
`locked`	boolean	no	Specifies if the runner is locked
`access_level`	string	no	The access level of the runner; `not_protected` or `ref_protected`
`maximum_timeout`	integer	no	Maximum timeout that limits the amount of time (in seconds) that runners can run jobs
`maintenance_note`	string	no	Free-form maintenance notes for the runner (1024 characters)

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"

The token attribute in the response was deprecated in GitLab 12.10 and removed in GitLab 13.0.

The active query parameter was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

Example response:

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "group_type",
    "contacted_at": "2016-01-25T16:39:48.066Z",
    "maintenance_note": null,
    "name": null,
    "online": true,
    "status": "online",
    "platform": null,
    "projects": [
        {
            "id": 1,
            "name": "GitLab Community Edition",
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
            "path": "gitlab-foss",
            "path_with_namespace": "gitlab-org/gitlab-foss"
        }
    ],
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql",
        "tag1",
        "tag2"
    ],
    "version": null,
    "access_level": "ref_protected",
    "maximum_timeout": null
}

Pause a runner

Pause a runner.

Prerequisites:

For instance_type, you must be an administrator of the GitLab instance.
For group_type, you must have the Owner role for the target namespace.
For project_type, you must have at least the Maintainer role for the target project.
An access token with the manage_runner scope and the appropriate role.

PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id

Attribute	Type	Required	Description
`runner_id`	integer	yes	The ID of a runner

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  "https://gitlab.example.com/api/v4/runners/6"

# --or--

# Deprecated: removal planned in 16.0
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  "https://gitlab.example.com/api/v4/runners/6"

The active form attribute was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

List jobs processed by a runner

History

List jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has at least the Reporter role.

GET /runners/:id/jobs

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner
`system_id`	string	no	System ID of the machine where the runner manager is running
`status`	string	no	Status of the job; one of: `running`, `success`, `failed`, `canceled`
`order_by`	string	no	Order jobs by `id`
`sort`	string	no	Sort jobs in `asc` or `desc` order (default: `desc`). If `sort` is specified, `order_by` must be specified as well

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

Example response:

[
    {
        "id": 2,
        "status": "running",
        "stage": "test",
        "name": "test",
        "ref": "main",
        "tag": false,
        "coverage": null,
        "created_at": "2017-11-16T08:50:29.000Z",
        "started_at": "2017-11-16T08:51:29.000Z",
        "finished_at": "2017-11-16T08:53:29.000Z",
        "duration": 120,
        "queued_duration": 2,
        "user": {
            "id": 1,
            "name": "John Doe2",
            "username": "user2",
            "state": "active",
            "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
            "web_url": "http://localhost/user2",
            "created_at": "2017-11-16T18:38:46.000Z",
            "bio": null,
            "location": null,
            "public_email": "",
            "skype": "",
            "linkedin": "",
            "twitter": "",
            "website_url": "",
            "organization": null
        },
        "commit": {
            "id": "97de212e80737a608d939f648d959671fb0a0142",
            "short_id": "97de212e",
            "title": "Update configuration\r",
            "created_at": "2017-11-16T08:50:28.000Z",
            "parent_ids": [
                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
                "498214de67004b1da3d820901307bed2a68a8ef6"
            ],
            "message": "See merge request !123",
            "author_name": "John Doe2",
            "author_email": "user2@example.org",
            "authored_date": "2017-11-16T08:50:27.000Z",
            "committer_name": "John Doe2",
            "committer_email": "user2@example.org",
            "committed_date": "2017-11-16T08:50:27.000Z"
        },
        "pipeline": {
            "id": 2,
            "sha": "97de212e80737a608d939f648d959671fb0a0142",
            "ref": "main",
            "status": "running"
        },
        "project": {
            "id": 1,
            "description": null,
            "name": "project1",
            "name_with_namespace": "John Doe2 / project1",
            "path": "project1",
            "path_with_namespace": "namespace1/project1",
            "created_at": "2017-11-16T18:38:46.620Z"
        }
    }
]

List runner’s managers

List all the managers of a runner.

GET /runners/:id/managers

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/managers"

Example response:

[
    {
      "id": 1,
      "system_id": "s_89e5e9956577",
      "version": "16.11.1",
      "revision": "535ced5f",
      "platform": "linux",
      "architecture": "amd64",
      "created_at": "2024-06-09T11:12:02.507Z",
      "contacted_at": "2024-06-09T06:30:09.355Z",
      "ip_address": "127.0.0.1",
      "status": "offline"
    },
    {
        "id": 2,
        "system_id": "runner-2",
        "version": "16.11.0",
        "revision": "91a27b2a",
        "platform": "linux",
        "architecture": "amd64",
        "created_at": "2024-06-09T09:12:02.507Z",
      "contacted_at": "2024-06-09T06:30:09.355Z",
        "ip_address": "127.0.0.1",
        "status": "offline",

    }
]

List project’s runners

List all runners available in the project, including from ancestor groups and any allowed instance runners.

Prerequisites:

You must be an administrator of or have at least the Maintainer role for the target project.

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project
`scope`	string	no	Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided
`type`	string	no	The type of runners to return, one of: `instance_type`, `group_type`, `project_type`
`status`	string	no	The status of runners to return, one of: `online`, `offline`, `stale`, or `never_contacted`. Other possible values are the deprecated `active` and `paused`. Requesting `offline` runners might also return `stale` runners because `stale` is included in `offline`.
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`tag_list`	string array	no	A list of runner tags
`version_prefix`	string	no	The prefix of the version of the runners to return. For example, `15.0`, `14`, `16.1.241`

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"

The active and paused values in the status query parameter were deprecated and will be removed in a future version of the REST API. They are replaced by the paused query parameter.

The active attribute in the response was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    }
]

Assign a runner to project

Assign an available project runner to the project.

Prerequisites:

For instance_type, you must be an administrator of the GitLab instance.
For group_type, you must have the Owner role for the target namespace.
For project_type, you must have at least the Maintainer role for the target project.

POST /projects/:id/runners

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project
`runner_id`	integer	yes	The ID of a runner

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \
     --form "runner_id=9"

Example response:

{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "ip_address": "",
    "is_shared": false,
    "runner_type": "project_type",
    "name": null,
    "online": true,
    "status": "online"
}

Unassign a runner from project

Unassign a project runner from the project. You cannot unassign a runner from the owner project. If you attempt this action, an error occurs. Use the call to delete a runner instead.

Prerequisites:

For instance_type, you must be an administrator of the GitLab instance.
For group_type, you must have the Owner role for the target namespace.
For project_type, you must have at least the Maintainer role for the target project.

DELETE /projects/:id/runners/:runner_id

Attribute	Type	Required	Description
`id`	integer/string	yes	The ID or URL-encoded path of the project
`runner_id`	integer	yes	The ID of a runner

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

List group’s runners

List all runners available in the group as well as its ancestor groups, including any allowed instance runners.

Prerequisites:

You must be an administrator or have the Maintainer role for the target namespace.

GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
GET /groups/:id/runners?tag_list=tag1,tag2

Attribute	Type	Required	Description
`id`	integer	yes	The ID of the group
`type`	string	no	The type of runners to return, one of: `instance_type`, `group_type`, `project_type`. The `project_type` value is deprecated and will be removed in GitLab 15.0
`status`	string	no	The status of runners to return, one of: `online`, `offline`, `stale`, or `never_contacted`. Other possible values are the deprecated `active` and `paused`. Requesting `offline` runners might also return `stale` runners because `stale` is included in `offline`.
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`tag_list`	string array	no	A list of runner tags
`version_prefix`	string	no	The prefix of the version of the runners to return. For example, `15.0`, `14`, `16.1.241`

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"

The active and paused values in the status query parameter were deprecated and will be removed in a future version of the REST API. They are replaced by the paused query parameter.

The active attribute in the response was deprecated and will be removed in a future version of the REST API. It is replaced by the paused attribute.

Example response:

[
  {
    "id": 3,
    "description": "Shared",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline"
  },
  {
    "id": 8,
    "description": "Test 2",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": false,
    "runner_type": "group_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  }
]

Create a runner

This endpoint returns an HTTP 410 Gone status code if registration with runner registration tokens is disabled in the project or group settings. If registration with runner registration tokens is disabled, use the POST /user/runners endpoint to create and register runners instead.

Create a runner with a runner registration token.

POST /runners

Attribute	Type	Required	Description
`token`	string	yes	Registration token
`description`	string	no	Description of the runner
`info`	hash	no	Runner’s metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version`, `platform`, and `architecture` are displayed in the Admin area of the UI
`active`	boolean	no	Deprecated: Use `paused` instead. Specifies if the runner is allowed to receive new jobs
`paused`	boolean	no	Specifies if the runner should ignore new jobs
`locked`	boolean	no	Specifies if the runner should be locked for the current project
`run_untagged`	boolean	no	Specifies if the runner should handle untagged jobs
`tag_list`	string array	no	A list of runner tags
`access_level`	string	no	The access level of the runner; `not_protected` or `ref_protected`
`maximum_timeout`	integer	no	Maximum timeout that limits the amount of time (in seconds) that runners can run jobs
`maintainer_note`	string	no	Deprecated, see `maintenance_note`
`maintenance_note`	string	no	Free-form maintenance notes for the runner (1024 characters)

curl --request POST "https://gitlab.example.com/api/v4/runners" \
     --form "token=<registration_token>" --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

Response:

Status	Description
201	Runner was created
403	Invalid runner registration token
410	Runner registration disabled

Example response:

{
    "id": 12345,
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Delete a runner

There are two ways to delete a runner:

By specifying the runner ID.
By specifying the runner’s authentication token.

Delete a runner by ID

To delete the runner by ID, use your access token with the runner’s ID:

Prerequisites:

For instance_type, you must be an administrator of the GitLab instance.
For group_type, you must have the Owner role for the target namespace.
For project_type, you must have at least the Maintainer role for the target project.
An access token with the manage_runner scope and the appropriate role.

DELETE /runners/:id

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner. The ID is visible in the UI under Settings > CI/CD. Expand Runners, and below the Remove Runner button is an ID preceded by the pound sign, for example, `#6`.

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

Delete a runner by authentication token

To delete the runner by using its authentication token:

Prerequisites:

You must be an administrator of or have the Owner role for the target namespace or project.
For instance_type, you must be an administrator of the GitLab instance.

DELETE /runners

Attribute	Type	Required	Description
`token`	string	yes	The runner’s authentication token.

curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

Response:

Status	Description
204	Runner was deleted

Verify authentication for a registered runner

Validates authentication credentials for a registered runner.

POST /runners/verify

Attribute	Type	Required	Description
`token`	string	yes	The runner’s authentication token.
`system_id`	string	no	The runner’s system identifier. This attribute is required if the `token` starts with `glrt-`.

curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

Response:

Status	Description
200	Credentials are valid
403	Credentials are invalid

Example response:

{
    "id": 12345,
    "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Reset instance’s runner registration token

Runner registration tokens, and support for certain configuration arguments, were deprecated in GitLab 15.6 and will be removed in GitLab 17.0. After GitLab 17.0, you will no longer be able to reset runner registration tokens and the reset_registration_token endpoint will not function.

Reset the runner registration token for the GitLab instance.

POST /runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/reset_registration_token"

Reset project’s runner registration token

Reset the runner registration token for a project.

POST /projects/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"

Reset group’s runner registration token

Reset the runner registration token for a group.

POST /groups/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"

Reset runner’s authentication token by using the runner ID

Reset the runner’s authentication token by using its runner ID.

Prerequisites:

For instance_type, you must be an administrator of the GitLab instance.
For group_type, you must have the Owner role for the target namespace.
For project_type, you must have at least the Maintainer role for the target project.
An access token with the manage_runner scope and the appropriate role.

POST /runners/:id/reset_authentication_token

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

Example response:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Reset runner’s authentication token by using the current token

Reset the runner’s authentication token by using the current token’s value as an input.

POST /runners/reset_authentication_token

Attribute	Type	Required	Description
`token`	string	yes	The authentication token of the runner

curl --request POST --form "token=<current token>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

Example response:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Runners API

Registration and authentication tokens

List owned runners

List all runners

Get runner’s details

Update runner’s details

Pause a runner

List jobs processed by a runner

List runner’s managers

List project’s runners

Assign a runner to project

Unassign a runner from project

List group’s runners

Create a runner

Delete a runner

Delete a runner by ID

Delete a runner by authentication token

Verify authentication for a registered runner

Reset instance’s runner registration token

Reset project’s runner registration token

Reset group’s runner registration token

Reset runner’s authentication token by using the runner ID

Reset runner’s authentication token by using the current token

Help & feedback

Docs

Product

Feature availability and product trials

Get help