debian-mirror-gitlab/doc/api/runners.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

854 lines
34 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Verify
group: Runner
2021-02-22 17:27:13 +05:30
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-23 00:09:42 +05:30
---
2021-11-11 11:23:49 +05:30
# Runners API **(FREE)**
2016-04-02 18:10:28 +05:30
2020-11-24 15:15:51 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5.
2016-04-02 18:10:28 +05:30
2019-07-07 11:18:12 +05:30
## Registration and authentication tokens
2020-11-24 15:15:51 +05:30
There are two tokens to take into account when connecting a runner with GitLab.
2019-07-07 11:18:12 +05:30
| Token | Description |
| ----- | ----------- |
2021-09-30 23:02:18 +05:30
| 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-05-07 20:08:51 +05:30
| 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-07-07 11:18:12 +05:30
2020-11-24 15:15:51 +05:30
Here's an example of how the two tokens are used in runner registration:
2019-07-07 11:18:12 +05:30
2020-11-24 15:15:51 +05:30
1. You register the runner via the GitLab API using a registration token, and an
2019-07-07 11:18:12 +05:30
authentication token is returned.
1. You use that authentication token and add it to the
2020-11-24 15:15:51 +05:30
[runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file):
2019-07-07 11:18:12 +05:30
2019-09-30 21:07:59 +05:30
```toml
[[runners]]
token = "<authentication_token>"
```
2019-07-07 11:18:12 +05:30
2020-11-24 15:15:51 +05:30
GitLab and the runner are then connected.
2019-07-07 11:18:12 +05:30
2016-04-02 18:10:28 +05:30
## List owned runners
Get a list of specific runners available to the user.
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
GET /runners
GET /runners?scope=active
2018-12-05 23:21:45 +05:30
GET /runners?type=project_type
2022-04-04 11:22:00 +05:30
GET /runners?status=online
GET /runners?paused=true
2019-07-07 11:18:12 +05:30
GET /runners?tag_list=tag1,tag2
2016-04-02 18:10:28 +05:30
```
2022-07-16 23:28:13 +05:30
| 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` |
| `status` | string | no | The status of runners to show, one of: `online`, `offline` 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 |
| `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-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
2016-04-02 18:10:28 +05:30
```
2022-04-04 11:22:00 +05:30
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-05-07 20:08:51 +05:30
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-04-04 11:22:00 +05:30
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2016-04-02 18:10:28 +05:30
Example response:
```json
[
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "test-1-20150125",
"id": 6,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2021-09-04 01:27:46 +05:30
"is_shared": false,
"runner_type": "project_type",
2018-03-17 18:26:18 +05:30
"name": null,
"online": true,
"status": "online"
2016-04-02 18:10:28 +05:30
},
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "test-2-20150125",
"id": 8,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "group_type",
2018-03-17 18:26:18 +05:30
"name": null,
"online": false,
"status": "offline"
2016-04-02 18:10:28 +05:30
}
]
```
2021-11-11 11:23:49 +05:30
## List all runners **(FREE SELF)**
2016-04-02 18:10:28 +05:30
Get a list of all runners in the GitLab instance (specific and shared). Access
2022-04-04 11:22:00 +05:30
is restricted to users with administrator access.
2016-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
GET /runners/all
GET /runners/all?scope=online
2018-12-05 23:21:45 +05:30
GET /runners/all?type=project_type
2022-04-04 11:22:00 +05:30
GET /runners/all?status=online
GET /runners/all?paused=true
2019-07-07 11:18:12 +05:30
GET /runners/all?tag_list=tag1,tag2
2016-04-02 18:10:28 +05:30
```
2022-04-04 11:22:00 +05:30
| 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-07 20:08:51 +05:30
| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-04-04 11:22:00 +05:30
| `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-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
2016-04-02 18:10:28 +05:30
```
2022-04-04 11:22:00 +05:30
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-05-07 20:08:51 +05:30
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-04-04 11:22:00 +05:30
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2016-04-02 18:10:28 +05:30
Example response:
```json
[
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "shared-runner-1",
"id": 1,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": true,
2021-09-04 01:27:46 +05:30
"runner_type": "instance_type",
2018-03-17 18:26:18 +05:30
"name": null,
"online": true,
"status": "online"
2016-04-02 18:10:28 +05:30
},
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "shared-runner-2",
"id": 3,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": true,
2021-09-04 01:27:46 +05:30
"runner_type": "instance_type",
2018-03-17 18:26:18 +05:30
"name": null,
2021-06-08 01:23:25 +05:30
"online": false,
2018-03-17 18:26:18 +05:30
"status": "offline"
2016-04-02 18:10:28 +05:30
},
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "test-1-20150125",
"id": 6,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "project_type",
2018-03-17 18:26:18 +05:30
"name": null,
2021-06-08 01:23:25 +05:30
"online": true,
2018-03-17 18:26:18 +05:30
"status": "paused"
2016-04-02 18:10:28 +05:30
},
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "test-2-20150125",
"id": 8,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "group_type",
2018-03-17 18:26:18 +05:30
"name": null,
"online": false,
"status": "offline"
2016-04-02 18:10:28 +05:30
}
]
```
2021-11-11 11:23:49 +05:30
To view more than the first 20 runners, use [pagination](index.md#pagination).
2016-04-02 18:10:28 +05:30
## Get runner's details
Get details of a runner.
2022-04-04 11:22:00 +05:30
At least the Maintainer role is required to get runner details at the
2021-09-04 01:27:46 +05:30
project and group level.
2021-04-29 21:17:54 +05:30
Instance-level runner details via this endpoint are available to all signed in users.
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
GET /runners/:id
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
2016-04-02 18:10:28 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2020-05-24 23:13:21 +05:30
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-22 19:07:51 +05:30
2022-04-04 11:22:00 +05:30
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2016-04-02 18:10:28 +05:30
Example response:
```json
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"architecture": null,
"description": "test-1-20150125",
"id": 6,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "project_type",
2016-04-02 18:10:28 +05:30
"contacted_at": "2016-01-25T16:39:48.066Z",
"name": null,
2018-03-17 18:26:18 +05:30
"online": true,
"status": "online",
2016-04-02 18:10:28 +05:30
"platform": null,
"projects": [
{
"id": 1,
"name": "GitLab Community Edition",
"name_with_namespace": "GitLab.org / GitLab Community Edition",
2019-12-21 20:55:43 +05:30
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-04-02 18:10:28 +05:30
}
],
"revision": null,
"tag_list": [
"ruby",
"mysql"
],
2018-03-17 18:26:18 +05:30
"version": null,
2018-05-09 12:01:36 +05:30
"access_level": "ref_protected",
"maximum_timeout": 3600
2016-04-02 18:10:28 +05:30
}
```
## Update runner's details
Update details of a runner.
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
PUT /runners/:id
```
2022-04-04 11:22:00 +05:30
| 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-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
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-04-02 18:10:28 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2021-11-11 11:23:49 +05:30
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-22 19:07:51 +05:30
2022-04-04 11:22:00 +05:30
NOTE:
The `active` query parameter was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2016-04-02 18:10:28 +05:30
Example response:
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "group_type",
2016-04-02 18:10:28 +05:30
"contacted_at": "2016-01-25T16:39:48.066Z",
"name": null,
2018-03-17 18:26:18 +05:30
"online": true,
"status": "online",
2016-04-02 18:10:28 +05:30
"platform": null,
"projects": [
{
"id": 1,
"name": "GitLab Community Edition",
"name_with_namespace": "GitLab.org / GitLab Community Edition",
2019-12-21 20:55:43 +05:30
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-04-02 18:10:28 +05:30
}
],
"revision": null,
"tag_list": [
"ruby",
"mysql",
"tag1",
"tag2"
],
2018-03-17 18:26:18 +05:30
"version": null,
2018-05-09 12:01:36 +05:30
"access_level": "ref_protected",
"maximum_timeout": null
2016-04-02 18:10:28 +05:30
}
```
2021-01-03 14:25:43 +05:30
### Pause a runner
2016-04-02 18:10:28 +05:30
2021-01-03 14:25:43 +05:30
Pause a specific runner.
2016-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2022-04-04 11:22:00 +05:30
PUT --form "paused=true" /runners/:runner_id
# --or--
2022-06-21 17:19:12 +05:30
# Deprecated: removal planned in 16.0
2022-04-04 11:22:00 +05:30
PUT --form "active=false" /runners/:runner_id
2016-04-02 18:10:28 +05:30
```
2021-01-03 14:25:43 +05:30
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
| `runner_id` | integer | yes | The ID of a runner |
2016-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```shell
2022-04-04 11:22:00 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "paused=true" "https://gitlab.example.com/api/v4/runners/6"
# --or--
2022-06-21 17:19:12 +05:30
# Deprecated: removal planned in 16.0
2021-09-04 01:27:46 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "active=false" "https://gitlab.example.com/api/v4/runners/6"
2016-04-02 18:10:28 +05:30
```
2022-04-04 11:22:00 +05:30
NOTE:
The `active` form attribute was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2018-03-17 18:26:18 +05:30
## List runner's jobs
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3.
2019-07-07 11:18:12 +05:30
2022-07-01 11:34:44 +05:30
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.
2018-03-17 18:26:18 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /runners/:id/jobs
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
| `status` | string | no | Status of the job; one of: `running`, `success`, `failed`, `canceled` |
2019-09-30 21:07:59 +05:30
| `order_by`| string | no | Order jobs by `id`. |
| `sort` | string | no | Sort jobs in `asc` or `desc` order (default: `desc`) |
2018-03-17 18:26:18 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
2018-03-17 18:26:18 +05:30
```
Example response:
```json
[
{
"id": 2,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2018-03-17 18:26:18 +05:30
"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,
"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,
2018-12-05 23:21:45 +05:30
"public_email": "",
2018-03-17 18:26:18 +05:30
"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": "master",
"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"
}
}
]
```
2016-04-02 18:10:28 +05:30
## List project's runners
2022-06-21 17:19:12 +05:30
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-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
GET /projects/:id/runners
2018-12-05 23:21:45 +05:30
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
2022-04-04 11:22:00 +05:30
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
2019-07-07 11:18:12 +05:30
GET /projects/:id/runners?tag_list=tag1,tag2
2016-04-02 18:10:28 +05:30
```
2022-04-04 11:22:00 +05:30
| 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-07 20:08:51 +05:30
| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-04-04 11:22:00 +05:30
| `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-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
2016-04-02 18:10:28 +05:30
```
2022-04-04 11:22:00 +05:30
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-05-07 20:08:51 +05:30
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-04-04 11:22:00 +05:30
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2016-04-02 18:10:28 +05:30
Example response:
```json
[
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "test-2-20150125",
"id": 8,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "project_type",
2018-03-17 18:26:18 +05:30
"name": null,
"online": false,
"status": "offline"
2016-04-02 18:10:28 +05:30
},
{
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2016-04-02 18:10:28 +05:30
"description": "development_runner",
"id": 5,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": true,
2021-09-04 01:27:46 +05:30
"runner_type": "instance_type",
2018-03-17 18:26:18 +05:30
"name": null,
2021-06-08 01:23:25 +05:30
"online": true,
2022-04-04 11:22:00 +05:30
"status": "online"
2016-04-02 18:10:28 +05:30
}
]
```
## Enable a runner in project
Enable an available specific runner in the project.
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
POST /projects/:id/runners
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-04-02 18:10:28 +05:30
| `runner_id` | integer | yes | The ID of a runner |
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \
--form "runner_id=9"
2016-04-02 18:10:28 +05:30
```
Example response:
```json
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
2018-11-08 19:23:39 +05:30
"ip_address": "127.0.0.1",
2016-04-02 18:10:28 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "project_type",
2018-03-17 18:26:18 +05:30
"name": null,
"online": true,
"status": "online"
2016-04-02 18:10:28 +05:30
}
```
## Disable a runner from project
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
2021-01-03 14:25:43 +05:30
returned. Use the call to [delete a runner](#delete-a-runner) instead.
2016-04-02 18:10:28 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-04-02 18:10:28 +05:30
DELETE /projects/:id/runners/:runner_id
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-04-02 18:10:28 +05:30
| `runner_id` | integer | yes | The ID of a runner |
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"
2016-04-02 18:10:28 +05:30
```
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
## List group's runners
2022-06-21 17:19:12 +05:30
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-04-22 19:07:51 +05:30
```plaintext
GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
2022-04-04 11:22:00 +05:30
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
2020-04-22 19:07:51 +05:30
GET /groups/:id/runners?tag_list=tag1,tag2
```
2022-04-04 11:22:00 +05:30
| 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-07 20:08:51 +05:30
| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 |
2022-04-04 11:22:00 +05:30
| `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-04-22 19:07:51 +05:30
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
```
2022-04-04 11:22:00 +05:30
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-05-07 20:08:51 +05:30
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-04-04 11:22:00 +05:30
NOTE:
The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211).
2022-05-07 20:08:51 +05:30
and will be removed in [GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute.
2022-04-04 11:22:00 +05:30
2020-04-22 19:07:51 +05:30
Example response:
```json
[
{
"id": 3,
"description": "Shared",
"ip_address": "127.0.0.1",
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2020-04-22 19:07:51 +05:30
"is_shared": true,
2021-09-04 01:27:46 +05:30
"runner_type": "instance_type",
2020-04-22 19:07:51 +05:30
"name": "gitlab-runner",
"online": null,
2022-07-16 23:28:13 +05:30
"status": "never_contacted"
2020-04-22 19:07:51 +05:30
},
{
"id": 6,
"description": "Test",
"ip_address": "127.0.0.1",
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2020-04-22 19:07:51 +05:30
"is_shared": true,
2021-09-04 01:27:46 +05:30
"runner_type": "instance_type",
2020-04-22 19:07:51 +05:30
"name": "gitlab-runner",
"online": false,
"status": "offline"
},
{
"id": 8,
"description": "Test 2",
"ip_address": "127.0.0.1",
"active": true,
2022-04-04 11:22:00 +05:30
"paused": false,
2020-04-22 19:07:51 +05:30
"is_shared": false,
2021-09-04 01:27:46 +05:30
"runner_type": "group_type",
2020-04-22 19:07:51 +05:30
"name": "gitlab-runner",
"online": null,
2022-07-16 23:28:13 +05:30
"status": "never_contacted"
2020-04-22 19:07:51 +05:30
}
]
```
2020-11-24 15:15:51 +05:30
## Register a new runner
2018-11-08 19:23:39 +05:30
2020-11-24 15:15:51 +05:30
Register a new runner for the instance.
2018-11-08 19:23:39 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
POST /runners
```
2022-04-04 11:22:00 +05:30
| Attribute | Type | Required | Description |
|--------------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `token` | string | yes | [Registration token](#registration-and-authentication-tokens) |
| `description` | string | no | Runner's description |
2022-07-16 23:28:13 +05:30
| `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-04-04 11:22:00 +05:30
| `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-05-07 20:08:51 +05:30
| `maintenance_note` | string | no | Free-form maintenance notes for the runner (1024 characters) |
2018-11-08 19:23:39 +05:30
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
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-11-08 19:23:39 +05:30
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 201 | Runner was created |
Example response:
```json
{
2021-03-11 19:13:27 +05:30
"id": 12345,
2022-04-04 11:22:00 +05:30
"token": "6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
2018-11-08 19:23:39 +05:30
}
```
2021-01-03 14:25:43 +05:30
## Delete a runner
There are two ways to delete a runner:
- By specifying the runner ID.
- By specifying the runner's authentication token.
2018-11-08 19:23:39 +05:30
2021-01-03 14:25:43 +05:30
### 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-11-08 19:23:39 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
DELETE /runners
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2021-01-03 14:25:43 +05:30
| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). |
2018-11-08 19:23:39 +05:30
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
--form "token=<authentication_token>"
2018-11-08 19:23:39 +05:30
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 204 | Runner was deleted |
2020-11-24 15:15:51 +05:30
## Verify authentication for a registered runner
2018-11-08 19:23:39 +05:30
2020-11-24 15:15:51 +05:30
Validates authentication credentials for a registered runner.
2018-11-08 19:23:39 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
POST /runners/verify
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2019-07-07 11:18:12 +05:30
| `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). |
2018-11-08 19:23:39 +05:30
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
--form "token=<authentication_token>"
2018-11-08 19:23:39 +05:30
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 200 | Credentials are valid |
| 403 | Credentials are invalid |
2021-11-11 11:23:49 +05:30
## Reset instance's runner registration token
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3.
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
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3.
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
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3.
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-11-18 22:05:49 +05:30
2022-05-07 20:08:51 +05:30
## Reset runner's authentication token by using the runner ID
2021-11-18 22:05:49 +05:30
2022-05-07 20:08:51 +05:30
Resets the runner's authentication token by using its runner ID.
2021-11-18 22:05:49 +05:30
```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-04-04 11:22:00 +05:30
"token": "6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
2021-11-18 22:05:49 +05:30
}
```
2022-05-07 20:08:51 +05:30
## 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"
}
```