2016-02-01 08:31:49 -05:00
# Runners API
2016-02-22 07:30:22 -05:00
> [Introduced][ce-2640] in GitLab 8.5
[ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640
2016-02-02 09:52:02 -05:00
## List owned runners
2016-02-01 08:31:49 -05:00
2016-02-05 06:25:16 -05:00
Get a list of specific runners available to the user.
2016-02-01 08:31:49 -05:00
```
GET /runners
2016-02-03 08:39:55 -05:00
GET /runners?scope=active
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|-----------|---------|----------|---------------------|
2016-02-05 06:25:16 -05:00
| `scope` | string | no | The scope of specific runners to show, one of: `active` , `paused` , `online` ; showing all runners if none provided |
2016-02-01 08:31:49 -05:00
```
2017-03-01 12:39:40 -05:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners"
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
Example response:
2016-02-01 08:31:49 -05:00
```json
[
{
"active": true,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
2017-05-27 09:23:27 -04:00
"name": null,
2017-06-13 16:03:34 -04:00
"online": true,
"status": "online"
2016-02-01 08:31:49 -05:00
},
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"is_shared": false,
2017-05-27 09:23:27 -04:00
"name": null,
2017-06-13 16:03:34 -04:00
"online": false,
"status": "offline"
2016-02-01 08:31:49 -05:00
}
]
```
2016-02-02 09:52:02 -05:00
## List all runners
2016-02-03 08:39:55 -05:00
Get a list of all runners in the GitLab instance (specific and shared). Access
is restricted to users with `admin` privileges.
2016-02-02 09:52:02 -05:00
```
GET /runners/all
2016-02-05 06:25:16 -05:00
GET /runners/all?scope=online
2016-02-02 09:52:02 -05:00
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
| `scope` | string | no | The scope of runners to show, one of: `specific` , `shared` , `active` , `paused` , `online` ; showing all runners if none provided |
```
2017-03-01 12:39:40 -05:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/all"
2016-02-02 09:52:02 -05:00
```
Example response:
```json
[
{
"active": true,
"description": "shared-runner-1",
"id": 1,
"is_shared": true,
2017-05-27 09:23:27 -04:00
"name": null,
2017-06-13 16:03:34 -04:00
"online": true,
"status": "online"
2016-02-02 09:52:02 -05:00
},
{
"active": true,
"description": "shared-runner-2",
"id": 3,
"is_shared": true,
2017-05-27 09:23:27 -04:00
"name": null,
"online": false
2017-06-13 16:03:34 -04:00
"status": "offline"
2016-02-02 09:52:02 -05:00
},
{
"active": true,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
2017-05-27 09:23:27 -04:00
"name": null,
"online": true
2017-06-13 16:03:34 -04:00
"status": "paused"
2016-02-02 09:52:02 -05:00
},
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"is_shared": false,
2017-05-27 09:23:27 -04:00
"name": null,
2017-06-13 16:03:34 -04:00
"online": false,
"status": "offline"
2016-02-02 09:52:02 -05:00
}
]
```
2016-02-01 08:31:49 -05:00
## Get runner's details
Get details of a runner.
```
GET /runners/:id
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
```
2017-03-01 12:39:40 -05:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6"
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
Example response:
2016-02-01 08:31:49 -05:00
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
2016-02-17 15:23:14 -05:00
"contacted_at": "2016-01-25T16:39:48.066Z",
2016-02-01 08:31:49 -05:00
"name": null,
2017-05-27 09:23:27 -04:00
"online": true,
2017-06-13 16:03:34 -04:00
"status": "online",
2016-02-01 08:31:49 -05:00
"platform": null,
2016-02-02 12:47:02 -05:00
"projects": [
{
"id": 1,
2016-02-17 15:06:21 -05:00
"name": "GitLab Community Edition",
2016-02-16 06:45:43 -05:00
"name_with_namespace": "GitLab.org / GitLab Community Edition",
2016-02-17 15:06:21 -05:00
"path": "gitlab-ce",
2016-02-16 06:45:43 -05:00
"path_with_namespace": "gitlab-org/gitlab-ce"
2016-02-02 12:47:02 -05:00
}
],
2016-02-04 04:33:29 -05:00
"token": "205086a8e3b9a2b818ffac9b89d102",
2016-02-01 08:31:49 -05:00
"revision": null,
"tag_list": [
"ruby",
"mysql"
],
2017-08-23 12:28:57 -04:00
"version": null,
2018-02-19 11:21:00 -05:00
"access_level": "ref_protected",
2018-03-06 10:14:23 -05:00
"maximum_timeout": 3600
2016-02-01 08:31:49 -05:00
}
```
## Update runner's details
Update details of a runner.
```
PUT /runners/:id
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|---------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
| `description` | string | no | The description of a runner |
| `active` | boolean | no | The state of a runner; can be set to `true` or `false` |
| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner |
2017-08-23 12:28:57 -04:00
| `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs |
| `locked` | boolean | no | Flag indicating the runner is locked |
2017-08-29 05:57:53 -04:00
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
2018-03-06 10:14:23 -05:00
| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
2016-02-01 08:31:49 -05:00
```
2017-03-01 12:39:40 -05:00
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
Example response:
2016-02-01 08:31:49 -05:00
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
"is_shared": false,
2016-02-17 15:23:14 -05:00
"contacted_at": "2016-01-25T16:39:48.066Z",
2016-02-01 08:31:49 -05:00
"name": null,
2017-05-27 09:23:27 -04:00
"online": true,
2017-06-13 16:03:34 -04:00
"status": "online",
2016-02-01 08:31:49 -05:00
"platform": null,
2016-02-10 08:20:51 -05:00
"projects": [
{
"id": 1,
2016-02-17 15:06:21 -05:00
"name": "GitLab Community Edition",
2016-02-16 06:45:43 -05:00
"name_with_namespace": "GitLab.org / GitLab Community Edition",
2016-02-17 15:06:21 -05:00
"path": "gitlab-ce",
2016-02-16 06:45:43 -05:00
"path_with_namespace": "gitlab-org/gitlab-ce"
2016-02-10 08:20:51 -05:00
}
],
"token": "205086a8e3b9a2b818ffac9b89d102",
2016-02-01 08:31:49 -05:00
"revision": null,
"tag_list": [
"ruby",
"mysql",
"tag1",
"tag2"
],
2017-08-23 12:28:57 -04:00
"version": null,
2018-02-19 11:21:00 -05:00
"access_level": "ref_protected",
2018-03-06 10:14:23 -05:00
"maximum_timeout": null
2016-02-01 08:31:49 -05:00
}
```
## Remove a runner
Remove a runner.
```
DELETE /runners/:id
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
```
2017-03-01 12:39:40 -05:00
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6"
2016-02-01 08:31:49 -05:00
```
2017-11-21 14:16:14 -05:00
## List runner's jobs
2017-11-16 11:12:33 -05:00
2017-11-21 14:16:14 -05:00
List jobs that are being processed or were processed by specified Runner.
2017-11-16 11:12:33 -05:00
```
GET /runners/:id/jobs
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
2017-11-21 14:16:14 -05:00
| `status` | string | no | Status of the job; one of: `running` , `success` , `failed` , `canceled` |
2017-11-16 11:12:33 -05:00
```
2017-11-21 14:16:14 -05:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
2017-11-16 11:12:33 -05:00
```
Example response:
```json
[
{
"id": 2,
"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 14:16:14 -05:00
"user": {
2017-11-16 11:12:33 -05:00
"id": 1,
2017-11-21 14:16:14 -05: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,
"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 11:12:33 -05:00
},
"pipeline": {
"id": 2,
"sha": "97de212e80737a608d939f648d959671fb0a0142",
"ref": "master",
2017-11-21 14:16:14 -05:00
"status": "running"
2017-11-16 13:44:14 -05: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 11:12:33 -05:00
}
}
]
```
2016-02-01 08:31:49 -05:00
## List project's runners
2016-02-03 08:39:55 -05:00
List all runners (specific and shared) available in the project. Shared runners
are listed if at least one shared runner is defined **and** shared runners
usage is enabled in the project's settings.
2016-02-01 08:31:49 -05:00
```
GET /projects/:id/runners
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|-----------|---------|----------|---------------------|
2017-04-08 05:21:11 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-02-01 08:31:49 -05:00
```
2017-03-01 12:39:40 -05:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners"
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
Example response:
2016-02-01 08:31:49 -05:00
```json
[
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"is_shared": false,
2017-05-27 09:23:27 -04:00
"name": null,
2017-06-13 16:03:34 -04:00
"online": false,
"status": "offline"
2016-02-01 08:31:49 -05:00
},
{
"active": true,
"description": "development_runner",
"id": 5,
"is_shared": true,
2017-05-27 09:23:27 -04:00
"name": null,
"online": true
2017-06-13 16:03:34 -04:00
"status": "paused"
2016-02-01 08:31:49 -05:00
}
]
```
## Enable a runner in project
2016-02-03 08:39:55 -05:00
Enable an available specific runner in the project.
2016-02-01 08:31:49 -05:00
```
2016-02-16 06:43:43 -05:00
POST /projects/:id/runners
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|-------------|---------|----------|---------------------|
2017-04-08 05:21:11 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-02-01 08:31:49 -05:00
| `runner_id` | integer | yes | The ID of a runner |
```
2017-03-01 12:39:40 -05:00
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9"
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
Example response:
2016-02-01 08:31:49 -05:00
```json
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
"is_shared": false,
2017-05-27 09:23:27 -04:00
"name": null,
2017-06-13 16:03:34 -04:00
"online": true,
"status": "online"
2016-02-01 08:31:49 -05:00
}
```
## Disable a runner from project
2016-02-03 08:39:55 -05: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
returned. Use the [Remove a runner ](#remove-a-runner ) call instead.
2016-02-01 08:31:49 -05:00
```
2016-02-02 08:52:33 -05:00
DELETE /projects/:id/runners/:runner_id
2016-02-01 08:31:49 -05:00
```
2016-02-02 07:22:51 -05:00
| Attribute | Type | Required | Description |
2016-02-01 08:31:49 -05:00
|-------------|---------|----------|---------------------|
2017-04-08 05:21:11 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-02-01 08:31:49 -05:00
| `runner_id` | integer | yes | The ID of a runner |
```
2017-03-01 12:39:40 -05:00
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9"
2016-02-01 08:31:49 -05:00
```
2018-01-16 03:29:48 -05:00
## Register a new Runner
Register a new Runner for the instance.
```
POST /runners
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
| `token` | string | yes | Registration token ([Read how to obtain a token](../ci/runners/README.md)) |
| `description` | string | no | Runner's description|
| `info` | hash | no | Runner's metadata |
| `active` | boolean| no | Whether the Runner is active |
| `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` | Array[String] | no | List of Runner's tags |
| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
```
curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=ipzXrMhuyyJPifUt6ANz" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 201 | Runner was created |
Example response:
```json
{
"id": "12345",
"token": "6337ff461c94fd3fa32ba3b1ff4125"
}
```
## Delete a registered Runner
Deletes a registed Runner.
```
DELETE /runners
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
| `token` | string | yes | Runner's authentication token |
```
curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e"
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 204 | Runner was deleted |
## Verify authentication for a registered Runner
Validates authentication credentials for a registered Runner.
```
POST /runners/verify
```
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
| `token` | string | yes | Runner's authentication token |
```
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e"
```
Response:
| Status | Description |
|-----------|---------------------------------|
| 200 | Credentials are valid |
| 403 | Credentials are invalid |