ContextQMD
Back to Gitlabhq

Runners API

doc/api/runners.md

18.11.242.7 KB
Original Source

{{< details >}}

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

{{< /details >}}

Use this API to manage runners registered to an instance.

To create new instance, group, or project runners, use the POST /user/runners endpoint. Use this API to manage existing runners.

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

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

Registration and authentication tokens

To connect a runner with GitLab, you need two tokens.

TokenDescription
Registration token (legacy)Token used to register the runner. It can be obtained through GitLab.
Authentication tokenToken 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 you can use the tokens for runner registration:

  1. Register the runner by using the GitLab API with a registration token to receive an authentication token.

  2. Add the authentication token to the runner's configuration file:

    toml
    [[runners]]
  token = "<authentication_token>"

GitLab and the runner are then connected.

List all available runners

Lists all runners available to the user.

Prerequisites:

  • For group runners, you must have the Owner role in the owner namespace.
  • For project runners, you must have the Security Manager, Maintainer or Owner role in a project assigned to the runner.
plaintext
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
AttributeTypeRequiredDescription
scopestringnoDeprecated: Use type or status instead. The scope of runners to return, one of: active, paused, online and offline; showing all runners if none provided
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type
statusstringnoThe 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.
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
version_prefixstringnoThe prefix of the version of the runners to return. For example, 15.0, 14, 16.1.241
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners"

[!warning] Deprecations:

  • The active and paused values in the status query parameter are deprecated and scheduled for removal in a future version of the REST API. Use the paused query parameter instead.
  • The active attribute in the response is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.
  • The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab 17.0, this attribute returns an empty string. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

json
[
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    }
]

List all runners

{{< details >}}

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

{{< /details >}}

Lists all runners in the GitLab instance (project and shared).

Prerequisites:

  • You must have either administrator access or auditor access.
plaintext
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
AttributeTypeRequiredDescription
scopestringnoDeprecated: 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
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type
statusstringnoThe 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.
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
version_prefixstringnoThe prefix of the version of the runners to return. For example, 15.0, 16.1.241
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/all"

> [!warning]
> Deprecations:
>
> - The `active` and `paused` values in the `status` query parameter are deprecated
>   and scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
>   Use the `paused` query parameter instead.
> - The `active` attribute in the response is deprecated
>   and is scheduled for removal in [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
>   Use the `paused` attribute instead.
> - The `ip_address` attribute in the response is deprecated
>   [in GitLab 16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/415159) and is scheduled for removal in
>   [a future version of the REST API](https://gitlab.com/gitlab-org/gitlab/-/issues/351109).
>   In GitLab 17.0, this attribute returns an empty string.
>   The `ipAddress` attribute can be found inside the respective runner manager.
>   It is only available through the GraphQL
>   [`CiRunnerManager` type](graphql/reference/_index.md#cirunnermanager).

Example response:

```json
[
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "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",
        "job_execution_status": "idle"
    }
]

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

Retrieve runner's details

Retrieves details of a runner.

Instance runner details are available to all authenticated users through this endpoint.

Prerequisites:

  • User access: You must have one of the following:
    • For group runners: The Maintainer or Owner role in the owner namespace.
    • For project runners: The Security Manager, Maintainer or Owner role in the project that owns the runner.
    • A custom role with the admin_runners permission in the relevant group or project.
  • An access token with the manage_runner scope and the appropriate role.
plaintext
GET /runners/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6"

[!warning] Deprecations:

Example response:

json
{
    "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",
    "job_execution_status": "idle",
    "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

Updates details of a runner.

plaintext
PUT /runners/:id

Prerequisites:

  • User access: You must have one of the following:
    • For instance runners: Administrator access to the GitLab instance.
    • For group runners: Owner role in the owner namespace.
    • For project runners: The Maintainer or Owner role in a project assigned to the runner.
    • A custom role with the admin_runners permission in the relevant group or project.
  • An access token with the manage_runner scope and the appropriate role.
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
descriptionstringnoThe description of the runner
activebooleannoDeprecated: Use paused instead. Flag indicating whether the runner is allowed to receive jobs
pausedbooleannoSpecifies if the runner should ignore new jobs
tag_listarraynoThe list of tags for the runner
run_untaggedbooleannoSpecifies if the runner can execute untagged jobs
lockedbooleannoSpecifies if the runner is locked
access_levelstringnoThe access level of the runner; not_protected or ref_protected
maximum_timeoutintegernoMaximum timeout that limits the amount of time (in seconds) that runners can run jobs
maintenance_notestringnoFree-form maintenance notes for the runner (1024 characters)
shell
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

[!warning] Deprecations:

Example response:

json
{
    "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",
    "job_execution_status": "idle",
    "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:

  • User access: You must have one of the following:
    • For instance runners: Administrator access to the GitLab instance.
    • For group runners: Owner role in the owner namespace.
    • For project runners: The Maintainer or Owner role in a project assigned to the runner.
    • A custom role with the admin_runners permission in the relevant group or project.
  • An access token with the manage_runner scope and the appropriate role.
plaintext
PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id
AttributeTypeRequiredDescription
runner_idintegeryesThe ID of a runner
shell
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  \
     --url "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"  \
     --url "https://gitlab.example.com/api/v4/runners/6"

[!warning] The active form attribute is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.

List all jobs processed by a runner

Lists all jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has the Reporter, Developer, Maintainer, or Owner role.

plaintext
GET /runners/:id/jobs
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
system_idstringnoSystem ID of the machine where the runner manager is running
statusstringnoStatus of the job; one of: running, success, failed, canceled
order_bystringnoOrder jobs by id
sortstringnoSort jobs in asc or desc order (default: desc). If sort is specified, order_by must be specified as well
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

Example response:

json
[
    {
        "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": "",
            "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": "[email protected]",
            "authored_date": "2017-11-16T08:50:27.000Z",
            "committer_name": "John Doe2",
            "committer_email": "[email protected]",
            "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 all runner's managers

Lists all the managers of a runner.

plaintext
GET /runners/:id/managers
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/managers"

Example response:

json
[
    {
      "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",
      "job_execution_status": "idle"
    },
    {
      "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",
      "job_execution_status": "idle"
    }
]

List all of a project's runners

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

Prerequisites:

  • You must be an administrator of the GitLab instance or have at least the Maintainer or Auditor role for the target project.
plaintext
GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners?status=online
GET /projects/:id/runners?paused=true
GET /projects/:id/runners?tag_list=tag1,tag2
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project
scopestringnoDeprecated: Use type or status instead. The scope of runners to return, one of: active, paused, online and offline; showing all runners if none provided
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type
statusstringnoThe 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.
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
version_prefixstringnoThe prefix of the version of the runners to return. For example, 15.0, 14, 16.1.241
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners"

[!warning] Deprecations:

  • The active and paused values in the status query parameter are deprecated and scheduled for removal in a future version of the REST API. Use the paused query parameter instead.
  • The active attribute in the response is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.
  • The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab 17.0, this attribute returns an empty string in GitLab 17.0. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

json
[
    {
        "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",
        "job_execution_status": "idle"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online",
        "job_execution_status": "idle"
    }
]

Assign a runner to project

Assign an available project runner to the project.

Prerequisites:

  • User access: You must have one of the following:

    • The Maintainer or Owner role for the project that owns the runner and the target project.
    • A custom role with the admin_runners permission in the relevant group or project.
plaintext
POST /projects/:id/runners
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project
runner_idintegeryesThe ID of a runner
shell
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners" \
     --form "runner_id=9"

[!warning] The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab 17.0, this attribute returns an empty string. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

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

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:

  • You must not lock the runner, unless you are an administrator.
  • User access: You must have one of the following:
    • The Maintainer or Owner role in the project you want to unassign.
    • A custom role with the admin_runners permission in the relevant group or project.
  • An access token with the manage_runner scope and the appropriate role.
plaintext
DELETE /projects/:id/runners/:runner_id
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the project
runner_idintegeryesThe ID of a runner
shell
curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/9/runners/9"

List all of a group's runners

Lists all runners available in the group and its ancestor groups, including any allowed instance runners.

Prerequisites:

  • User access: You must have one of the following:
    • Administrator access to the GitLab instance.
    • Owner or Auditor role in the group.
    • A custom role with the admin_runners permission in the group.
  • An access token with the manage_runner scope and the appropriate role.
plaintext
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
AttributeTypeRequiredDescription
idintegeryesThe ID of the group
typestringnoThe type of runners to return, one of: instance_type, group_type, project_type. The project_type value is deprecated and is scheduled for removal in GitLab 15.0
statusstringnoThe 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.
pausedbooleannoWhether to include only runners that are accepting or ignoring new jobs
tag_liststring arraynoA list of runner tags
version_prefixstringnoThe prefix of the version of the runners to return. For example, 15.0, 14, 16.1.241

[!warning] Deprecations:

  • The active and paused values in the status query parameter are deprecated and scheduled for removal in a future version of the REST API. Use the paused query parameter instead.
  • The active attribute in the response is deprecated and is scheduled for removal in a future version of the REST API. Use the paused attribute instead.
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/groups/9/runners"

[!warning] The ip_address attribute in the response is deprecated in GitLab 16.1 and is scheduled for removal in a future version of the REST API. In GitLab, the attribute returns an empty string. The ipAddress attribute can be found inside the respective runner manager. It is only available through the GraphQL CiRunnerManager type.

Example response:

json
[
  {
    "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",
    "job_execution_status": "idle"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline",
    "job_execution_status": "idle"
  },
  {
    "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",
    "job_execution_status": "idle"
  }
]

Create a runner

[!warning] The endpoint uses registration tokens (deprecated), which are disabled by default in GitLab 17.0 and later. Use POST /user/runners instead to create runners with the recommended workflow.

Create a runner with a runner registration token.

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.

plaintext
POST /runners
AttributeTypeRequiredDescription
tokenstringyesRegistration token
descriptionstringnoDescription of the runner
infohashnoRunner'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
activebooleannoDeprecated: Use paused instead. Specifies if the runner is allowed to receive new jobs
pausedbooleannoSpecifies if the runner should ignore new jobs
lockedbooleannoSpecifies if the runner should be locked for the current project
run_untaggedbooleannoSpecifies if the runner should handle untagged jobs
tag_liststring arraynoA list of runner tags
access_levelstringnoThe access level of the runner; not_protected or ref_protected
maximum_timeoutintegernoMaximum timeout that limits the amount of time (in seconds) that runners can run jobs
maintainer_notestringnoDeprecated, see maintenance_note
maintenance_notestringnoFree-form maintenance notes for the runner (1024 characters)
shell
curl --request POST \
     --url "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:

StatusDescription
201Runner was created
403Invalid runner registration token
410Runner registration disabled

Example response:

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

Delete a runner

You can delete a runner by specifying the:

  • Runner ID
  • 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:

  • User access: You must have one of the following:
    • For instance runners: Administrator access to the GitLab instance.
    • For group runners: Owner role in the owner namespace.
    • For project runners: The Maintainer or Owner role in the project that owns the runner.
    • A custom role with the admin_runners permission in the relevant group or project.
  • An access token with the manage_runner scope and the appropriate role.
plaintext
DELETE /runners/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner. The ID is visible in the UI under Settings > CI/CD. Expand Runners, and below Remove Runner is an ID preceded by the pound sign, for example, #6.
shell
curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6"

Delete a runner by authentication token

Delete the runner by using its authentication token.

plaintext
DELETE /runners
AttributeTypeRequiredDescription
tokenstringyesThe runner's authentication token.
shell
curl --request DELETE \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

Response:

StatusDescription
204Runner was deleted

Verify authentication for a registered runner

Validates authentication credentials for a registered runner.

plaintext
POST /runners/verify
AttributeTypeRequiredDescription
tokenstringyesThe runner's authentication token.
system_idstringnoThe runner's system identifier. This attribute is required if the token starts with glrt-.
shell
curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

Response:

StatusDescription
200Credentials are valid
403Credentials are invalid

Example response:

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

Reset instance's runner registration token

[!warning] The option to pass runner registration tokens and support for certain configuration arguments is considered legacy and is not recommended. Use the runner creation workflow to generate an authentication token to register runners. This process provides full traceability of runner ownership and enhances your runner fleet's security.

For more information, see Migrating to the new runner registration workflow.

Reset the runner registration token for the GitLab instance.

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

Reset project's runner registration token

[!warning] The option to pass runner registration tokens and support for certain configuration arguments is considered legacy and is not recommended. Use the runner creation workflow to generate an authentication token to register runners. This process provides full traceability of runner ownership and enhances your runner fleet's security. For more information, see Migrating to the new runner registration workflow.

Reset the runner registration token for a project.

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

Reset group's runner registration token

[!warning] The option to pass runner registration tokens and support for certain configuration arguments is considered legacy and is not recommended. Use the runner creation workflow to generate an authentication token to register runners. This process provides full traceability of runner ownership and enhances your runner fleet's security. For more information, see Migrating to the new runner registration workflow.

Reset the runner registration token for a group.

plaintext
POST /groups/:id/runners/reset_registration_token
shell
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "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:

  • User access: You must have one of the following:
    • For instance runners: Administrator access to the GitLab instance.
    • For group runners: Owner role in the owner namespace.
    • For project runners: The Maintainer or Owner role in a project assigned to the runner.
    • A custom role with the admin_runners permission in the relevant group or project.
  • An access token with the manage_runner scope and the appropriate role.
plaintext
POST /runners/:id/reset_authentication_token
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
shell
curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

Example response:

json
{
    "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.

plaintext
POST /runners/reset_authentication_token
AttributeTypeRequiredDescription
tokenstringyesThe authentication token of the runner
shell
curl --request POST \
     --form "token=<current token>" \
     --url "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

Example response:

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

Discover Job Router information

{{< history >}}

{{< /history >}}

Get Job Router discovery information for a runner.

Prerequisites:

  • You must provide a valid runner authentication token.
plaintext
GET /runners/router/discovery
shell
curl --header "Runner-Token: <runner_authentication_token>" \
     --url "https://gitlab.example.com/api/v4/runners/router/discovery"

Response:

The response contains the following fields:

AttributeTypeDescription
server_urlstringURL to the Job Router

The response returns with one of the following status codes:

StatusDescription
200Job Router information retrieved successfully
403Forbidden
501Job Router is not available

Example response:

json
{
    "server_url": "wss://kas.example.com"
}