2020-06-17 03:08:38 +00:00
---
stage: Verify
group: Runner
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-17 03:08:38 +00:00
---
2021-09-07 21:10:59 +00:00
# Runners API **(FREE)**
2016-02-01 13:31:49 +00:00
2020-08-22 00:10:21 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5.
2016-02-22 12:30:22 +00:00
2019-04-05 04:52:00 +00:00
## Registration and authentication tokens
2020-08-22 00:10:21 +00:00
There are two tokens to take into account when connecting a runner with GitLab.
2019-04-05 04:52:00 +00:00
| Token | Description |
| ----- | ----------- |
2021-06-28 12:38:12 +00:00
| Registration token | Token used to [register the runner ](https://docs.gitlab.com/runner/register/ ). It can be [obtained through GitLab ](../ci/runners/index.md ). |
2022-02-23 03:17:13 +00:00
| Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained automatically when you [register a runner ](https://docs.gitlab.com/runner/register/ ) or by the Runner API when you manually [register a runner ](#register-a-new-runner ) or [reset the authentication token ](#reset-runners-authentication-token-by-using-the-runner-id ). |
2019-04-05 04:52:00 +00:00
2020-08-22 00:10:21 +00:00
Here's an example of how the two tokens are used in runner registration:
2019-04-05 04:52:00 +00:00
2020-08-22 00:10:21 +00:00
1. You register the runner via the GitLab API using a registration token, and an
2019-04-05 04:52:00 +00:00
authentication token is returned.
1. You use that authentication token and add it to the
2020-08-22 00:10:21 +00:00
[runner's configuration file ](https://docs.gitlab.com/runner/commands/#configuration-file ):
2019-04-05 04:52:00 +00:00
2019-07-09 07:16:17 +00:00
```toml
[[runners]]
token = "< authentication_token > "
```
2019-04-05 04:52:00 +00:00
2020-08-22 00:10:21 +00:00
GitLab and the runner are then connected.
2019-04-05 04:52:00 +00:00
2016-02-02 14:52:02 +00:00
## List owned runners
2016-02-01 13:31:49 +00:00
2016-02-05 11:25:16 +00:00
Get a list of specific runners available to the user.
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-01 13:31:49 +00:00
GET /runners
2016-02-03 13:39:55 +00:00
GET /runners?scope=active
2018-06-11 11:37:47 +00:00
GET /runners?type=project_type
2022-01-31 18:18:10 +00:00
GET /runners?status=online
GET /runners?paused=true
2018-06-11 16:04:46 +00:00
GET /runners?tag_list=tag1,tag2
2016-02-01 13:31:49 +00:00
```
2022-05-11 21:08:09 +00:00
| Attribute | Type | Required | Description |
|------------|--------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active` , `paused` , `online` and `offline` ; showing all runners if none provided |
| `type` | string | no | The type of runners to show, one of: `instance_type` , `group_type` , `project_type` |
2022-05-24 21:09:08 +00:00
| `status` | string | no | The status of runners to show, one of: `online` , `offline` , `stale` , and `never_contacted` . `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-05-11 21:08:09 +00:00
| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs |
| `tag_list` | string array | no | List of the runner's tags |
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/runners"
2016-02-01 13:31:49 +00:00
```
2022-01-31 18:18:10 +00:00
NOTE:
The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). They are replaced by the `paused` query parameter.
2022-01-31 18:18:10 +00:00
2022-01-28 12:17:26 +00:00
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2016-02-02 12:22:51 +00:00
Example response:
2016-02-01 13:31:49 +00:00
```json
[
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-01 13:31:49 +00:00
"description": "test-1-20150125",
"id": 6,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2021-06-07 15:09:56 +00:00
"is_shared": false,
"runner_type": "project_type",
2017-05-27 13:23:27 +00:00
"name": null,
2017-06-13 20:03:34 +00:00
"online": true,
"status": "online"
2016-02-01 13:31:49 +00:00
},
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-01 13:31:49 +00:00
"description": "test-2-20150125",
"id": 8,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-01 13:31:49 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "group_type",
2017-05-27 13:23:27 +00:00
"name": null,
2017-06-13 20:03:34 +00:00
"online": false,
"status": "offline"
2016-02-01 13:31:49 +00:00
}
]
```
2021-09-07 21:10:59 +00:00
## List all runners **(FREE SELF)**
2016-02-02 14:52:02 +00:00
2016-02-03 13:39:55 +00:00
Get a list of all runners in the GitLab instance (specific and shared). Access
2022-02-02 15:17:50 +00:00
is restricted to users with administrator access.
2016-02-02 14:52:02 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-02 14:52:02 +00:00
GET /runners/all
2016-02-05 11:25:16 +00:00
GET /runners/all?scope=online
2018-06-11 11:37:47 +00:00
GET /runners/all?type=project_type
2022-01-31 18:18:10 +00:00
GET /runners/all?status=online
GET /runners/all?paused=true
2018-06-11 16:04:46 +00:00
GET /runners/all?tag_list=tag1,tag2
2016-02-02 14:52:02 +00:00
```
2022-01-31 18:18:10 +00:00
| Attribute | Type | Required | Description |
|------------|--------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific` , `shared` , `active` , `paused` , `online` and `offline` ; showing all runners if none provided |
| `type` | string | no | The type of runners to show, one of: `instance_type` , `group_type` , `project_type` |
2022-05-24 21:09:08 +00:00
| `status` | string | no | The status of runners to show, one of: `online` , `offline` , `stale` , and `never_contacted` . `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-01-31 18:18:10 +00:00
| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs |
| `tag_list` | string array | no | List of the runner's tags |
2016-02-02 14:52:02 +00:00
2020-02-28 03:09:04 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/runners/all"
2016-02-02 14:52:02 +00:00
```
2022-01-31 18:18:10 +00:00
NOTE:
The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). They are replaced by the `paused` query parameter.
2022-01-31 18:18:10 +00:00
2022-01-28 12:17:26 +00:00
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2016-02-02 14:52:02 +00:00
Example response:
```json
[
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-02 14:52:02 +00:00
"description": "shared-runner-1",
"id": 1,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-02 14:52:02 +00:00
"is_shared": true,
2021-06-07 15:09:56 +00:00
"runner_type": "instance_type",
2017-05-27 13:23:27 +00:00
"name": null,
2017-06-13 20:03:34 +00:00
"online": true,
"status": "online"
2016-02-02 14:52:02 +00:00
},
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-02 14:52:02 +00:00
"description": "shared-runner-2",
"id": 3,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-02 14:52:02 +00:00
"is_shared": true,
2021-06-07 15:09:56 +00:00
"runner_type": "instance_type",
2017-05-27 13:23:27 +00:00
"name": null,
2021-04-29 12:09:58 +00:00
"online": false,
2017-06-13 20:03:34 +00:00
"status": "offline"
2016-02-02 14:52:02 +00:00
},
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-02 14:52:02 +00:00
"description": "test-1-20150125",
"id": 6,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-02 14:52:02 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "project_type",
2017-05-27 13:23:27 +00:00
"name": null,
2021-04-29 12:09:58 +00:00
"online": true,
2017-06-13 20:03:34 +00:00
"status": "paused"
2016-02-02 14:52:02 +00:00
},
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-02 14:52:02 +00:00
"description": "test-2-20150125",
"id": 8,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-02 14:52:02 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "group_type",
2017-05-27 13:23:27 +00:00
"name": null,
2017-06-13 20:03:34 +00:00
"online": false,
"status": "offline"
2016-02-02 14:52:02 +00:00
}
]
```
2021-09-14 15:12:05 +00:00
To view more than the first 20 runners, use [pagination ](index.md#pagination ).
2016-02-01 13:31:49 +00:00
## Get runner's details
Get details of a runner.
2022-01-31 00:14:49 +00:00
At least the Maintainer role is required to get runner details at the
2021-05-31 18:09:56 +00:00
project and group level.
2021-04-09 03:09:05 +00:00
Instance-level runner details via this endpoint are available to all signed in users.
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-01 13:31:49 +00:00
GET /runners/:id
```
2016-02-02 12:22:51 +00:00
| Attribute | Type | Required | Description |
2016-02-01 13:31:49 +00:00
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
2020-02-28 03:09:04 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/runners/6"
2016-02-01 13:31:49 +00:00
```
2020-12-04 21:09:29 +00:00
NOTE:
2020-05-13 12:07:54 +00:00
The `token` attribute in the response was deprecated [in GitLab 12.10 ](https://gitlab.com/gitlab-org/gitlab/-/issues/214320 ).
and removed in [GitLab 13.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/214322 ).
2020-04-15 12:09:18 +00:00
2022-01-28 12:17:26 +00:00
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2016-02-02 12:22:51 +00:00
Example response:
2016-02-01 13:31:49 +00:00
```json
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-01 13:31:49 +00:00
"architecture": null,
"description": "test-1-20150125",
"id": 6,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-01 13:31:49 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "project_type",
2016-02-17 20:23:14 +00:00
"contacted_at": "2016-01-25T16:39:48.066Z",
2016-02-01 13:31:49 +00:00
"name": null,
2017-05-27 13:23:27 +00:00
"online": true,
2017-06-13 20:03:34 +00:00
"status": "online",
2016-02-01 13:31:49 +00:00
"platform": null,
2016-02-02 17:47:02 +00:00
"projects": [
{
"id": 1,
2016-02-17 20:06:21 +00:00
"name": "GitLab Community Edition",
2016-02-16 11:45:43 +00:00
"name_with_namespace": "GitLab.org / GitLab Community Edition",
2019-09-18 18:06:14 +00:00
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-02-02 17:47:02 +00:00
}
],
2016-02-01 13:31:49 +00:00
"revision": null,
"tag_list": [
"ruby",
"mysql"
],
2017-08-23 16:28:57 +00:00
"version": null,
2018-02-19 16:21:00 +00:00
"access_level": "ref_protected",
2018-03-06 15:14:23 +00:00
"maximum_timeout": 3600
2016-02-01 13:31:49 +00:00
}
```
## Update runner's details
Update details of a runner.
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-01 13:31:49 +00:00
PUT /runners/:id
```
2022-01-28 12:17:26 +00:00
| Attribute | Type | Required | Description |
|-------------------|---------|----------|--------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID of a runner |
| `description` | string | no | The description of a runner |
| `active` | boolean | no | Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs |
| `paused` | boolean | no | Flag indicating whether the runner should ignore new jobs |
| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner |
| `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs |
| `locked` | boolean | no | Flag indicating 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 set when this runner handles the job |
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```shell
2021-06-02 15:09:59 +00:00
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"
2016-02-01 13:31:49 +00:00
```
2020-12-04 21:09:29 +00:00
NOTE:
2021-09-07 21:10:59 +00:00
The `token` attribute in the response was [deprecated ](https://gitlab.com/gitlab-org/gitlab/-/issues/214320 ) in GitLab 12.10.
and [removed ](https://gitlab.com/gitlab-org/gitlab/-/issues/214322 ) in GitLab 13.0.
2020-04-15 12:09:18 +00:00
2022-01-28 12:17:26 +00:00
NOTE:
The `active` query parameter was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2016-02-02 12:22:51 +00:00
Example response:
2016-02-01 13:31:49 +00:00
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-01 13:31:49 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "group_type",
2016-02-17 20:23:14 +00:00
"contacted_at": "2016-01-25T16:39:48.066Z",
2016-02-01 13:31:49 +00:00
"name": null,
2017-05-27 13:23:27 +00:00
"online": true,
2017-06-13 20:03:34 +00:00
"status": "online",
2016-02-01 13:31:49 +00:00
"platform": null,
2016-02-10 13:20:51 +00:00
"projects": [
{
"id": 1,
2016-02-17 20:06:21 +00:00
"name": "GitLab Community Edition",
2016-02-16 11:45:43 +00:00
"name_with_namespace": "GitLab.org / GitLab Community Edition",
2019-09-18 18:06:14 +00:00
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-02-10 13:20:51 +00:00
}
],
2016-02-01 13:31:49 +00:00
"revision": null,
"tag_list": [
"ruby",
"mysql",
"tag1",
"tag2"
],
2017-08-23 16:28:57 +00:00
"version": null,
2018-02-19 16:21:00 +00:00
"access_level": "ref_protected",
2018-03-06 15:14:23 +00:00
"maximum_timeout": null
2016-02-01 13:31:49 +00:00
}
```
2020-10-07 18:08:34 +00:00
### Pause a runner
Pause a specific runner.
```plaintext
2022-01-28 12:17:26 +00:00
PUT --form "paused=true" /runners/:runner_id
2022-01-31 00:14:49 +00:00
# --or--
2022-01-28 12:17:26 +00:00
2022-03-29 18:08:06 +00:00
# Deprecated: removal planned in 16.0
2022-01-28 12:17:26 +00:00
PUT --form "active=false" /runners/:runner_id
2020-10-07 18:08:34 +00:00
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
| `runner_id` | integer | yes | The ID of a runner |
```shell
2022-01-28 12:17:26 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " \
--form "paused=true" "https://gitlab.example.com/api/v4/runners/6"
# --or--
2022-03-29 18:08:06 +00:00
# Deprecated: removal planned in 16.0
2021-06-02 15:09:59 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " \
--form "active=false" "https://gitlab.example.com/api/v4/runners/6"
2020-10-07 18:08:34 +00:00
```
2022-01-28 12:17:26 +00:00
NOTE:
The `active` form attribute was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2017-11-21 19:16:14 +00:00
## List runner's jobs
2017-11-16 16:12:33 +00:00
2020-02-06 15:09:11 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3.
2019-04-01 07:53:18 +00:00
2020-08-22 00:10:21 +00:00
List jobs that are being processed or were processed by specified runner.
2017-11-16 16:12:33 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2017-11-16 16:12:33 +00:00
GET /runners/:id/jobs
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
2017-11-21 19:16:14 +00:00
| `status` | string | no | Status of the job; one of: `running` , `success` , `failed` , `canceled` |
2019-06-12 20:03:21 +00:00
| `order_by` | string | no | Order jobs by `id` . |
2022-06-06 18:09:02 +00:00
| `sort` | string | no | Sort jobs in `asc` or `desc` order (default: `desc` ). Specify `order_by` as well, including for `id` . |
2017-11-16 16:12:33 +00:00
2020-02-28 03:09:04 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
2017-11-16 16:12:33 +00:00
```
Example response:
```json
[
{
"id": 2,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2017-11-16 16:12:33 +00:00
"status": "running",
"stage": "test",
"name": "test",
"ref": "master",
"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,
2017-11-21 19:16:14 +00:00
"user": {
2017-11-16 16:12:33 +00:00
"id": 1,
2017-11-21 19:16:14 +00:00
"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,
2018-09-25 16:40:24 +00:00
"public_email": "",
2017-11-21 19:16:14 +00:00
"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"
2017-11-16 16:12:33 +00:00
},
"pipeline": {
"id": 2,
"sha": "97de212e80737a608d939f648d959671fb0a0142",
"ref": "master",
2017-11-21 19:16:14 +00:00
"status": "running"
2017-11-16 18:44:14 +00:00
},
"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"
2017-11-16 16:12:33 +00:00
}
}
]
```
2016-02-01 13:31:49 +00:00
## List project's runners
2022-04-07 18:08:29 +00:00
List all runners available in the project, including from ancestor groups and [any allowed shared runners ](../ci/runners/runners_scope.md#enable-shared-runners-for-a-project ).
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-01 13:31:49 +00:00
GET /projects/:id/runners
2018-06-11 13:25:00 +00:00
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
2022-01-31 18:18:10 +00:00
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
2018-06-11 16:04:46 +00:00
GET /projects/:id/runners?tag_list=tag1,tag2
2016-02-01 13:31:49 +00:00
```
2022-01-31 18:18:10 +00:00
| Attribute | Type | Required | Description |
|------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active` , `paused` , `online` and `offline` ; showing all runners if none provided |
| `type` | string | no | The type of runners to show, one of: `instance_type` , `group_type` , `project_type` |
2022-05-24 21:09:08 +00:00
| `status` | string | no | The status of runners to show, one of: `online` , `offline` , `stale` , and `never_contacted` . `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-01-31 18:18:10 +00:00
| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs |
| `tag_list` | string array | no | List of the runner's tags |
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/9/runners"
2016-02-01 13:31:49 +00:00
```
2022-01-31 18:18:10 +00:00
NOTE:
The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). They are replaced by the `paused` query parameter.
2022-01-31 18:18:10 +00:00
2022-01-28 12:17:26 +00:00
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2016-02-02 12:22:51 +00:00
Example response:
2016-02-01 13:31:49 +00:00
```json
[
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-01 13:31:49 +00:00
"description": "test-2-20150125",
"id": 8,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-01 13:31:49 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "project_type",
2017-05-27 13:23:27 +00:00
"name": null,
2017-06-13 20:03:34 +00:00
"online": false,
"status": "offline"
2016-02-01 13:31:49 +00:00
},
{
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2016-02-01 13:31:49 +00:00
"description": "development_runner",
"id": 5,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-01 13:31:49 +00:00
"is_shared": true,
2021-06-07 15:09:56 +00:00
"runner_type": "instance_type",
2017-05-27 13:23:27 +00:00
"name": null,
2021-04-29 12:09:58 +00:00
"online": true,
2022-01-28 12:17:26 +00:00
"status": "online"
2016-02-01 13:31:49 +00:00
}
]
```
## Enable a runner in project
2016-02-03 13:39:55 +00:00
Enable an available specific runner in the project.
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-16 11:43:43 +00:00
POST /projects/:id/runners
2016-02-01 13:31:49 +00:00
```
2016-02-02 12:22:51 +00:00
| Attribute | Type | Required | Description |
2016-02-01 13:31:49 +00:00
|-------------|---------|----------|---------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-02-01 13:31:49 +00:00
| `runner_id` | integer | yes | The ID of a runner |
2020-02-28 03:09:04 +00:00
```shell
2021-06-02 15:09:59 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/9/runners" \
--form "runner_id=9"
2016-02-01 13:31:49 +00:00
```
2016-02-02 12:22:51 +00:00
Example response:
2016-02-01 13:31:49 +00:00
```json
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
2018-06-22 09:50:32 +00:00
"ip_address": "127.0.0.1",
2016-02-01 13:31:49 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "project_type",
2017-05-27 13:23:27 +00:00
"name": null,
2017-06-13 20:03:34 +00:00
"online": true,
"status": "online"
2016-02-01 13:31:49 +00:00
}
```
## Disable a runner from project
2016-02-03 13:39:55 +00:00
Disable a specific runner from the project. It works only if the project isn't
the only project associated with the specified runner. If so, an error is
2020-09-24 21:09:38 +00:00
returned. Use the call to [delete a runner ](#delete-a-runner ) instead.
2016-02-01 13:31:49 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2016-02-02 13:52:33 +00:00
DELETE /projects/:id/runners/:runner_id
2016-02-01 13:31:49 +00:00
```
2016-02-02 12:22:51 +00:00
| Attribute | Type | Required | Description |
2016-02-01 13:31:49 +00:00
|-------------|---------|----------|---------------------|
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-02-01 13:31:49 +00:00
| `runner_id` | integer | yes | The ID of a runner |
2020-02-28 03:09:04 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/9/runners/9"
2016-02-01 13:31:49 +00:00
```
2018-01-16 08:29:48 +00:00
2020-03-30 18:08:07 +00:00
## List group's runners
2022-04-07 18:08:29 +00:00
List all runners available in the group as well as its ancestor groups, including [any allowed shared runners ](../ci/runners/runners_scope.md#enable-shared-runners-for-a-group ).
2020-03-30 18:08:07 +00:00
```plaintext
GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
2022-01-31 18:18:10 +00:00
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
2020-03-30 18:08:07 +00:00
GET /groups/:id/runners?tag_list=tag1,tag2
```
2022-02-02 09:16:48 +00:00
| Attribute | Type | Required | Description |
|------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID of the group owned by the authenticated user |
| `type` | string | no | The type of runners to show, one of: `instance_type` , `group_type` , `project_type` . The `project_type` value is [deprecated ](https://gitlab.com/gitlab-org/gitlab/-/issues/351466 ) and will be removed in GitLab 15.0 |
2022-05-24 21:09:08 +00:00
| `status` | string | no | The status of runners to show, one of: `online` , `offline` , `stale` , and `never_contacted` . `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-02-02 09:16:48 +00:00
| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs |
| `tag_list` | string array | no | List of the runner's tags |
2020-03-30 18:08:07 +00:00
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/9/runners"
```
2022-01-31 18:18:10 +00:00
NOTE:
The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). They are replaced by the `paused` query parameter.
2022-01-31 18:18:10 +00:00
2022-01-28 12:17:26 +00:00
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8 ](https://gitlab.com/gitlab-org/gitlab/-/issues/347211 ).
2022-03-02 09:13:50 +00:00
and will be removed in [GitLab 16.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/351109 ). It is replaced by the `paused` attribute.
2022-01-28 12:17:26 +00:00
2020-03-30 18:08:07 +00:00
Example response:
```json
[
{
"id": 3,
"description": "Shared",
"ip_address": "127.0.0.1",
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2020-03-30 18:08:07 +00:00
"is_shared": true,
2021-06-07 15:09:56 +00:00
"runner_type": "instance_type",
2020-03-30 18:08:07 +00:00
"name": "gitlab-runner",
"online": null,
2022-05-11 21:08:09 +00:00
"status": "never_contacted"
2020-03-30 18:08:07 +00:00
},
{
"id": 6,
"description": "Test",
"ip_address": "127.0.0.1",
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2020-03-30 18:08:07 +00:00
"is_shared": true,
2021-06-07 15:09:56 +00:00
"runner_type": "instance_type",
2020-03-30 18:08:07 +00:00
"name": "gitlab-runner",
"online": false,
"status": "offline"
},
{
"id": 8,
"description": "Test 2",
"ip_address": "127.0.0.1",
"active": true,
2022-01-28 12:17:26 +00:00
"paused": false,
2020-03-30 18:08:07 +00:00
"is_shared": false,
2021-06-07 15:09:56 +00:00
"runner_type": "group_type",
2020-03-30 18:08:07 +00:00
"name": "gitlab-runner",
"online": null,
2022-05-11 21:08:09 +00:00
"status": "never_contacted"
2020-03-30 18:08:07 +00:00
}
]
```
2020-08-22 00:10:21 +00:00
## Register a new runner
2018-01-16 08:29:48 +00:00
2020-08-22 00:10:21 +00:00
Register a new runner for the instance.
2018-01-16 08:29:48 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2018-01-16 08:29:48 +00:00
POST /runners
```
2022-01-28 12:17:26 +00:00
| Attribute | Type | Required | Description |
|--------------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token` | string | yes | [Registration token ](#registration-and-authentication-tokens ) |
| `description` | string | no | Runner's description |
2022-05-11 15:07:26 +00:00
| `info` | hash | no | Runner's metadata. You can include `name` , `version` , `revision` , `platform` , and `architecture` , but only `version` is displayed in the Admin Area of the UI |
2022-01-28 12:17:26 +00:00
| `active` | boolean | no | Deprecated: Use `:paused` instead. Whether the runner is allowed to receive jobs |
| `paused` | boolean | no | Whether the runner should ignore new jobs |
| `locked` | boolean | no | Whether the runner should be locked for current project |
| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs |
| `tag_list` | string array | no | List of runner's tags |
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job |
| `maintainer_note` | string | no | [Deprecated ](https://gitlab.com/gitlab-org/gitlab/-/issues/350730 ), see `maintenance_note` |
2022-02-22 00:14:20 +00:00
| `maintenance_note` | string | no | Free-form maintenance notes for the runner (1024 characters) |
2018-01-16 08:29:48 +00:00
2020-02-28 03:09:04 +00:00
```shell
2021-06-02 15:09:59 +00:00
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"
2018-01-16 08:29:48 +00:00
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 201 | Runner was created |
Example response:
```json
{
2021-01-21 18:09:11 +00:00
"id": 12345,
2022-02-16 15:14:05 +00:00
"token": "6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
2018-01-16 08:29:48 +00:00
}
```
2020-09-24 21:09:38 +00:00
## Delete a runner
There are two ways to delete a runner:
- By specifying the runner ID.
- By specifying the runner's authentication token.
2018-01-16 08:29:48 +00:00
2020-09-24 21:09:38 +00:00
### Delete a runner by ID
To delete the runner by ID, use your access token with the runner's ID:
```plaintext
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` . |
```shell
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:
2018-01-16 08:29:48 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2018-01-16 08:29:48 +00:00
DELETE /runners
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2020-09-24 21:09:38 +00:00
| `token` | string | yes | The runner's [authentication token ](#registration-and-authentication-tokens ). |
2018-01-16 08:29:48 +00:00
2020-02-28 03:09:04 +00:00
```shell
2021-06-02 15:09:59 +00:00
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
--form "token=< authentication_token > "
2018-01-16 08:29:48 +00:00
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 204 | Runner was deleted |
2020-08-22 00:10:21 +00:00
## Verify authentication for a registered runner
2018-01-16 08:29:48 +00:00
2020-08-22 00:10:21 +00:00
Validates authentication credentials for a registered runner.
2018-01-16 08:29:48 +00:00
2020-02-28 03:09:04 +00:00
```plaintext
2018-01-16 08:29:48 +00:00
POST /runners/verify
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2019-04-05 04:52:00 +00:00
| `token` | string | yes | Runner's [authentication token ](#registration-and-authentication-tokens ). |
2018-01-16 08:29:48 +00:00
2020-02-28 03:09:04 +00:00
```shell
2021-06-02 15:09:59 +00:00
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
--form "token=< authentication_token > "
2018-01-16 08:29:48 +00:00
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 200 | Credentials are valid |
| 403 | Credentials are invalid |
2021-09-01 03:11:03 +00:00
## Reset instance's runner registration token
2021-09-17 03:11:13 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3.
2021-09-01 03:11:03 +00:00
Resets the runner registration token for the GitLab instance.
```plaintext
POST /runners/reset_registration_token
```
```shell
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
2021-09-17 03:11:13 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3.
2021-09-01 03:11:03 +00:00
Resets 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 > " \
"https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"
```
## Reset group's runner registration token
2021-09-17 03:11:13 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3.
2021-09-01 03:11:03 +00:00
Resets 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 > " \
"https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"
```
2021-09-21 12:11:06 +00:00
2022-02-23 03:17:13 +00:00
## Reset runner's authentication token by using the runner ID
2021-09-21 12:11:06 +00:00
2022-02-23 03:17:13 +00:00
Resets the runner's authentication token by using its runner ID.
2021-09-21 12:11:06 +00:00
```plaintext
POST /runners/:id/reset_authentication_token
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " \
"https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"
```
Example response:
```json
{
2022-02-16 15:14:05 +00:00
"token": "6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
2021-09-21 12:11:06 +00:00
}
```
2022-02-23 03:17:13 +00:00
## Reset runner's authentication token by using the current token
Resets the runner's authentication token by using the current token's value as an input.
```plaintext
POST /runners/reset_authentication_token
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------------------|
| `token` | string | yes | The current token of the runner |
```shell
curl --request POST --form "token=< current token > " \
"https://gitlab.example.com/api/v4/runners/reset_authentication_token"
```
Example response:
```json
{
"token": "6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
}
```