runners.md 15.1 KB
Newer Older
1 2
# Runners API

3 4 5 6
> [Introduced][ce-2640] in GitLab 8.5

[ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640

7
## List owned runners
8

9
Get a list of specific runners available to the user.
10 11 12

```
GET /runners
13
GET /runners?scope=active
14
GET /runners?type=project_type
15
GET /runners?status=active
16 17
```

18
| Attribute | Type    | Required | Description         |
19
|-----------|---------|----------|---------------------|
20
| `scope`   | string  | no       | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided |
21
| `type`    | string  | no       | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` |
22
| `status`  | string  | no       | The status of runners to show, one of: `active`, `paused`, `online`, `offline` |
23 24

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

28 29
Example response:

30 31 32 33 34 35 36
```json
[
    {
        "active": true,
        "description": "test-1-20150125",
        "id": 6,
        "is_shared": false,
37
        "ip_address": "127.0.0.1",
38
        "name": null,
39 40
        "online": true,
        "status": "online"
41 42 43 44 45
    },
    {
        "active": true,
        "description": "test-2-20150125",
        "id": 8,
46
        "ip_address": "127.0.0.1",
47
        "is_shared": false,
48
        "name": null,
49 50
        "online": false,
        "status": "offline"
51 52 53 54
    }
]
```

55 56
## List all runners

57 58
Get a list of all runners in the GitLab instance (specific and shared). Access
is restricted to users with `admin` privileges.
59 60 61

```
GET /runners/all
62
GET /runners/all?scope=online
63
GET /runners/all?type=project_type
64
GET /runners/all?status=active
65 66 67 68
```

| Attribute | Type    | Required | Description         |
|-----------|---------|----------|---------------------|
69
| `scope`   | string  | no       | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided |
70
| `type`    | string  | no       | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` |
71
| `status`  | string  | no       | The status of runners to show, one of: `active`, `paused`, `online`, `offline` |
72 73

```
74
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
75 76 77 78 79 80 81 82 83 84
```

Example response:

```json
[
    {
        "active": true,
        "description": "shared-runner-1",
        "id": 1,
85
        "ip_address": "127.0.0.1",
86
        "is_shared": true,
87
        "name": null,
88 89
        "online": true,
        "status": "online"
90 91 92 93 94
    },
    {
        "active": true,
        "description": "shared-runner-2",
        "id": 3,
95
        "ip_address": "127.0.0.1",
96
        "is_shared": true,
97 98
        "name": null,
        "online": false
99
        "status": "offline"
100 101 102 103 104
    },
    {
        "active": true,
        "description": "test-1-20150125",
        "id": 6,
105
        "ip_address": "127.0.0.1",
106
        "is_shared": false,
107 108
        "name": null,
        "online": true
109
        "status": "paused"
110 111 112 113 114
    },
    {
        "active": true,
        "description": "test-2-20150125",
        "id": 8,
115
        "ip_address": "127.0.0.1",
116
        "is_shared": false,
117
        "name": null,
118 119
        "online": false,
        "status": "offline"
120 121 122 123
    }
]
```

124 125 126 127 128 129 130 131
## Get runner's details

Get details of a runner.

```
GET /runners/:id
```

132
| Attribute | Type    | Required | Description         |
133 134 135 136
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |

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

140 141
Example response:

142 143 144 145 146 147
```json
{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
148
    "ip_address": "127.0.0.1",
149
    "is_shared": false,
150
    "contacted_at": "2016-01-25T16:39:48.066Z",
151
    "name": null,
152
    "online": true,
153
    "status": "online",
154
    "platform": null,
155 156 157
    "projects": [
        {
            "id": 1,
158
            "name": "GitLab Community Edition",
159
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
160
            "path": "gitlab-ce",
161
            "path_with_namespace": "gitlab-org/gitlab-ce"
162 163
        }
    ],
164
    "token": "205086a8e3b9a2b818ffac9b89d102",
165 166 167 168 169
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql"
    ],
Shinya Maeda's avatar
Shinya Maeda committed
170
    "version": null,
171
    "access_level": "ref_protected",
172
    "maximum_timeout": 3600
173 174 175 176 177 178 179 180 181 182 183
}
```

## Update runner's details

Update details of a runner.

```
PUT /runners/:id
```

184
| Attribute     | Type    | Required | Description         |
185 186 187 188 189
|---------------|---------|----------|---------------------|
| `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 |
Shinya Maeda's avatar
Shinya Maeda committed
190 191
| `run_untagged`    | boolean   | no       | Flag indicating the runner can execute untagged jobs |
| `locked`    | boolean   | no       | Flag indicating the runner is locked |
Shinya Maeda's avatar
Shinya Maeda committed
192
| `access_level`    | string   | no       | The access_level of the runner; `not_protected` or `ref_protected` |
193
| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
194 195

```
196
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"
197 198
```

199 200
Example response:

201 202 203 204 205 206
```json
{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
207
    "ip_address": "127.0.0.1",
208
    "is_shared": false,
209
    "contacted_at": "2016-01-25T16:39:48.066Z",
210
    "name": null,
211
    "online": true,
212
    "status": "online",
213
    "platform": null,
214 215 216
    "projects": [
        {
            "id": 1,
217
            "name": "GitLab Community Edition",
218
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
219
            "path": "gitlab-ce",
220
            "path_with_namespace": "gitlab-org/gitlab-ce"
221 222 223
        }
    ],
    "token": "205086a8e3b9a2b818ffac9b89d102",
224 225 226 227 228 229 230
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql",
        "tag1",
        "tag2"
    ],
Shinya Maeda's avatar
Shinya Maeda committed
231
    "version": null,
232
    "access_level": "ref_protected",
233
    "maximum_timeout": null
234 235 236 237 238 239 240 241 242 243 244
}
```

## Remove a runner

Remove a runner.

```
DELETE /runners/:id
```

245
| Attribute | Type    | Required | Description         |
246 247 248 249
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |

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

Tomasz Maczukin's avatar
Tomasz Maczukin committed
253
## List runner's jobs
254

Tomasz Maczukin's avatar
Tomasz Maczukin committed
255
List jobs that are being processed or were processed by specified Runner.
256 257 258 259 260 261 262 263

```
GET /runners/:id/jobs
```

| Attribute | Type    | Required | Description         |
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |
Tomasz Maczukin's avatar
Tomasz Maczukin committed
264
| `status`  | string  | no       | Status of the job; one of: `running`, `success`, `failed`, `canceled` |
265 266

```
267
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
268 269 270 271 272 273 274 275
```

Example response:

```json
[
    {
        "id": 2,
276
        "ip_address": "127.0.0.1",
277 278 279 280 281 282 283 284 285 286
        "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,
Tomasz Maczukin's avatar
Tomasz Maczukin committed
287
        "user": {
288
            "id": 1,
Tomasz Maczukin's avatar
Tomasz Maczukin committed
289 290 291 292 293 294 295 296
            "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,
297
            "public_email": "",
Tomasz Maczukin's avatar
Tomasz Maczukin committed
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
            "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"
320 321 322 323 324
        },
        "pipeline": {
            "id": 2,
            "sha": "97de212e80737a608d939f648d959671fb0a0142",
            "ref": "master",
Tomasz Maczukin's avatar
Tomasz Maczukin committed
325
            "status": "running"
326 327 328 329 330 331 332 333 334
        },
        "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"
335 336 337 338 339
        }
    }
]
```

340 341
## List project's runners

342
List all runners (specific and shared) available in the project. Shared runners
343
are listed if at least one shared runner is defined.
344 345 346

```
GET /projects/:id/runners
347 348 349
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners?status=active
350 351
```

352 353
| Attribute | Type           | Required | Description         |
|-----------|----------------|----------|---------------------|
354
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
355
| `scope`   | string         | no       | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided |
356 357
| `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: `active`, `paused`, `online`, `offline` |
358 359

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

363 364
Example response:

365 366 367 368 369 370
```json
[
    {
        "active": true,
        "description": "test-2-20150125",
        "id": 8,
371
        "ip_address": "127.0.0.1",
372
        "is_shared": false,
373
        "name": null,
374 375
        "online": false,
        "status": "offline"
376 377 378 379 380
    },
    {
        "active": true,
        "description": "development_runner",
        "id": 5,
381
        "ip_address": "127.0.0.1",
382
        "is_shared": true,
383 384
        "name": null,
        "online": true
385
        "status": "paused"
386 387 388 389 390 391
    }
]
```

## Enable a runner in project

392
Enable an available specific runner in the project.
393 394

```
395
POST /projects/:id/runners
396 397
```

398
| Attribute   | Type    | Required | Description         |
399
|-------------|---------|----------|---------------------|
400
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
401 402 403
| `runner_id` | integer | yes      | The ID of a runner  |

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

407 408
Example response:

409 410 411 412 413
```json
{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
414
    "ip_address": "127.0.0.1",
415
    "is_shared": false,
416
    "name": null,
417 418
    "online": true,
    "status": "online"
419 420 421 422 423
}
```

## Disable a runner from project

424 425 426
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.
427 428

```
429
DELETE /projects/:id/runners/:runner_id
430 431
```

432
| Attribute   | Type    | Required | Description         |
433
|-------------|---------|----------|---------------------|
434
| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
435 436 437
| `runner_id` | integer | yes      | The ID of a runner  |

```
438
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"
439
```
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522

## 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         |