jobs.md 27.7 KB
Newer Older
1
# Jobs API
Tomasz Maczukin's avatar
Tomasz Maczukin committed
2

3
## List project jobs
Tomasz Maczukin's avatar
Tomasz Maczukin committed
4

5
Get a list of jobs in a project.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
6 7

```
8
GET /projects/:id/jobs
Tomasz Maczukin's avatar
Tomasz Maczukin committed
9 10
```

11 12
| Attribute | Type                           | Required | Description                                                                                                                                                                                                    |
|-----------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
13
| `id`      | integer/string                 | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                                                                               |
14
| `scope`   | string **or** array of strings | no       | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. |
15

16
```sh
17
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running'
18 19
```

Tomasz Maczukin's avatar
Tomasz Maczukin committed
20
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
21

22 23 24 25 26 27 28 29 30 31 32 33 34
```json
[
  {
    "commit": {
      "author_email": "admin@example.com",
      "author_name": "Administrator",
      "created_at": "2015-12-24T16:51:14.000+01:00",
      "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "message": "Test the CI integration.",
      "short_id": "0ff3ae19",
      "title": "Test the CI integration."
    },
    "coverage": null,
Élie's avatar
Élie committed
35
    "created_at": "2015-12-24T15:51:21.727Z",
36
    "started_at": "2015-12-24T17:54:24.729Z",
Élie's avatar
Élie committed
37
    "finished_at": "2015-12-24T17:54:24.921Z",
38
    "duration": 0.192,
Élie's avatar
Élie committed
39 40 41
    "artifacts_expire_at": "2016-01-23T17:54:24.921Z",
    "id": 6,
    "name": "rspec:other",
42 43 44 45 46 47 48
    "pipeline": {
      "id": 6,
      "ref": "master",
      "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "status": "pending"
    },
    "ref": "master",
49
    "artifacts": [],
50 51 52 53
    "runner": null,
    "stage": "test",
    "status": "failed",
    "tag": false,
54
    "web_url": "https://example.com/foo/bar/-/jobs/6",
55 56 57 58
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
59 60
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
61
      "web_url": "http://gitlab.dev/root",
62 63 64
      "created_at": "2015-12-21T13:14:24.077Z",
      "bio": null,
      "location": null,
65
      "public_email": "",
66 67 68 69 70
      "skype": "",
      "linkedin": "",
      "twitter": "",
      "website_url": "",
      "organization": ""
71 72 73 74 75 76 77 78 79 80 81 82 83
    }
  },
  {
    "commit": {
      "author_email": "admin@example.com",
      "author_name": "Administrator",
      "created_at": "2015-12-24T16:51:14.000+01:00",
      "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "message": "Test the CI integration.",
      "short_id": "0ff3ae19",
      "title": "Test the CI integration."
    },
    "coverage": null,
Élie's avatar
Élie committed
84
    "created_at": "2015-12-24T15:51:21.802Z",
85 86 87
    "started_at": "2015-12-24T17:54:27.722Z",
    "finished_at": "2015-12-24T17:54:27.895Z",
    "duration": 0.173,
Élie's avatar
Élie committed
88 89 90 91
    "artifacts_file": {
      "filename": "artifacts.zip",
      "size": 1000
    },
92 93 94 95 96 97
    "artifacts": [
      {"file_type": "archive", "size": 1000, "filename": "artifacts.zip", "file_format": "zip"},
      {"file_type": "metadata", "size": 186, "filename": "metadata.gz", "file_format": "gzip"},
      {"file_type": "trace", "size": 1500, "filename": "job.log", "file_format": "raw"},
      {"file_type": "junit", "size": 750, "filename": "junit.xml.gz", "file_format": "gzip"}
    ],
98
    "artifacts_expire_at": "2016-01-23T17:54:27.895Z",
Élie's avatar
Élie committed
99 100
    "id": 7,
    "name": "teaspoon",
101 102 103 104 105 106 107
    "pipeline": {
      "id": 6,
      "ref": "master",
      "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "status": "pending"
    },
    "ref": "master",
108
    "artifacts": [],
109 110 111 112
    "runner": null,
    "stage": "test",
    "status": "failed",
    "tag": false,
113
    "web_url": "https://example.com/foo/bar/-/jobs/7",
114 115 116 117
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
118 119
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
120
      "web_url": "http://gitlab.dev/root",
121 122 123
      "created_at": "2015-12-21T13:14:24.077Z",
      "bio": null,
      "location": null,
124
      "public_email": "",
125 126 127 128 129
      "skype": "",
      "linkedin": "",
      "twitter": "",
      "website_url": "",
      "organization": ""
130 131 132 133 134 135 136 137 138 139
    }
  }
]
```

## List pipeline jobs

Get a list of jobs for a pipeline.

```
140
GET /projects/:id/pipelines/:pipeline_id/jobs
141 142
```

143 144
| Attribute     | Type                           | Required | Description                                                                                                                                                                                                    |
|---------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
145 146
| `id`          | integer/string                 | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                                                                               |
| `pipeline_id` | integer                        | yes      | ID of a pipeline.                                                                                                                                                                                          |
147
| `scope`       | string **or** array of strings | no       | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. |
148

149
```sh
150
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running'
151 152 153 154
```

Example of response

Tomasz Maczukin's avatar
Tomasz Maczukin committed
155 156
```json
[
157 158 159 160 161 162 163 164 165 166 167
  {
    "commit": {
      "author_email": "admin@example.com",
      "author_name": "Administrator",
      "created_at": "2015-12-24T16:51:14.000+01:00",
      "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "message": "Test the CI integration.",
      "short_id": "0ff3ae19",
      "title": "Test the CI integration."
    },
    "coverage": null,
Élie's avatar
Élie committed
168
    "created_at": "2015-12-24T15:51:21.727Z",
169
    "started_at": "2015-12-24T17:54:24.729Z",
Élie's avatar
Élie committed
170
    "finished_at": "2015-12-24T17:54:24.921Z",
171
    "duration": 0.192,
172
    "artifacts_expire_at": "2016-01-23T17:54:24.921Z",
Élie's avatar
Élie committed
173 174
    "id": 6,
    "name": "rspec:other",
175 176 177 178 179
    "pipeline": {
      "id": 6,
      "ref": "master",
      "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "status": "pending"
180
    },
181
    "ref": "master",
182
    "artifacts": [],
183 184 185 186
    "runner": null,
    "stage": "test",
    "status": "failed",
    "tag": false,
187
    "web_url": "https://example.com/foo/bar/-/jobs/6",
188 189 190 191
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
192 193
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
194
      "web_url": "http://gitlab.dev/root",
195 196 197
      "created_at": "2015-12-21T13:14:24.077Z",
      "bio": null,
      "location": null,
198
      "public_email": "",
199 200 201 202 203
      "skype": "",
      "linkedin": "",
      "twitter": "",
      "website_url": "",
      "organization": ""
204 205 206 207 208 209 210 211 212 213 214
    }
  },
  {
    "commit": {
      "author_email": "admin@example.com",
      "author_name": "Administrator",
      "created_at": "2015-12-24T16:51:14.000+01:00",
      "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "message": "Test the CI integration.",
      "short_id": "0ff3ae19",
      "title": "Test the CI integration."
Tomasz Maczukin's avatar
Tomasz Maczukin committed
215
    },
216
    "coverage": null,
Élie's avatar
Élie committed
217
    "created_at": "2015-12-24T15:51:21.802Z",
218 219 220
    "started_at": "2015-12-24T17:54:27.722Z",
    "finished_at": "2015-12-24T17:54:27.895Z",
    "duration": 0.173,
Élie's avatar
Élie committed
221 222 223 224
    "artifacts_file": {
      "filename": "artifacts.zip",
      "size": 1000
    },
225 226 227 228 229 230
    "artifacts": [
      {"file_type": "archive", "size": 1000, "filename": "artifacts.zip", "file_format": "zip"},
      {"file_type": "metadata", "size": 186, "filename": "metadata.gz", "file_format": "gzip"},
      {"file_type": "trace", "size": 1500, "filename": "job.log", "file_format": "raw"},
      {"file_type": "junit", "size": 750, "filename": "junit.xml.gz", "file_format": "gzip"}
    ],
231
    "artifacts_expire_at": "2016-01-23T17:54:27.895Z",
Élie's avatar
Élie committed
232 233
    "id": 7,
    "name": "teaspoon",
234 235 236 237 238
    "pipeline": {
      "id": 6,
      "ref": "master",
      "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "status": "pending"
239
    },
240
    "ref": "master",
241
    "artifacts": [],
242 243 244 245
    "runner": null,
    "stage": "test",
    "status": "failed",
    "tag": false,
246
    "web_url": "https://example.com/foo/bar/-/jobs/7",
247 248 249 250
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
251 252
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
253
      "web_url": "http://gitlab.dev/root",
254 255 256
      "created_at": "2015-12-21T13:14:24.077Z",
      "bio": null,
      "location": null,
257
      "public_email": "",
258 259 260 261 262
      "skype": "",
      "linkedin": "",
      "twitter": "",
      "website_url": "",
      "organization": ""
Tomasz Maczukin's avatar
Tomasz Maczukin committed
263
    }
264
  }
Tomasz Maczukin's avatar
Tomasz Maczukin committed
265
]
Tomasz Maczukin's avatar
Tomasz Maczukin committed
266 267
```

268
## Get a single job
Tomasz Maczukin's avatar
Tomasz Maczukin committed
269

270
Get a single job of a project
Tomasz Maczukin's avatar
Tomasz Maczukin committed
271 272

```
273
GET /projects/:id/jobs/:job_id
Tomasz Maczukin's avatar
Tomasz Maczukin committed
274 275
```

276 277
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
278 279
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
280

281
```sh
282
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8"
283 284
```

Tomasz Maczukin's avatar
Tomasz Maczukin committed
285
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
286 287 288

```json
{
289 290 291 292 293 294 295 296 297 298 299
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "created_at": "2015-12-24T15:51:21.880Z",
300
  "started_at": "2015-12-24T17:54:30.733Z",
301
  "finished_at": "2015-12-24T17:54:31.198Z",
302
  "duration": 0.465,
303
  "artifacts_expire_at": "2016-01-23T17:54:31.198Z",
304 305
  "id": 8,
  "name": "rubocop",
306 307 308 309 310
  "pipeline": {
    "id": 6,
    "ref": "master",
    "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "status": "pending"
311
  },
312
  "ref": "master",
313
  "artifacts": [],
314 315 316 317
  "runner": null,
  "stage": "test",
  "status": "failed",
  "tag": false,
318
  "web_url": "https://example.com/foo/bar/-/jobs/8",
319 320 321 322
  "user": {
    "id": 1,
    "name": "Administrator",
    "username": "root",
323 324
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
325
    "web_url": "http://gitlab.dev/root",
326 327 328
    "created_at": "2015-12-21T13:14:24.077Z",
    "bio": null,
    "location": null,
329
    "public_email": "",
330 331 332 333 334
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": ""
335
  }
Tomasz Maczukin's avatar
Tomasz Maczukin committed
336 337 338
}
```

339
## Get job artifacts
340

341
> **Notes**:
342
>
343
> - [Introduced][ce-2893] in GitLab 8.5.
344

345
Get job artifacts of a project.
346 347

```
348
GET /projects/:id/jobs/:job_id/artifacts
349 350
```

351 352
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
353 354
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
355

356 357
Example requests:

358
```sh
359
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts"
360 361
```

362
Possible response status codes:
363 364 365 366 367 368

| Status    | Description                     |
|-----------|---------------------------------|
| 200       | Serves the artifacts file       |
| 404       | Build not found or no artifacts |

369 370
[ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893

371
## Download the artifacts archive
372

373
> **Notes**:
374
>
375
> - [Introduced][ce-5347] in GitLab 8.10.
376

377
Download the artifacts archive from the given reference name and job provided the
378
job finished successfully.
379 380

```
381
GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
382 383 384 385
```

Parameters

386 387
| Attribute  | Type           | Required | Description                                                                                                      |
|------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
388
| `id`       | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
389 390
| `ref_name` | string         | yes      | Branch or tag name in repository. HEAD or SHA references are not supported.                                      |
| `job`      | string         | yes      | The name of the job.                                                                                             |
391

392
Example requests:
393

394
```sh
395
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
396 397
```

398
Possible response status codes:
399 400 401 402 403 404 405 406

| Status    | Description                     |
|-----------|---------------------------------|
| 200       | Serves the artifacts file       |
| 404       | Build not found or no artifacts |

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

407
## Download a single artifact file by job ID
408 409 410

> Introduced in GitLab 10.0

411 412 413
Download a single artifact file from a job with a specified ID from within
the job's artifacts archive. The file is extracted from the archive and
streamed to the client.
414 415 416 417 418 419 420

```
GET /projects/:id/jobs/:job_id/artifacts/*artifact_path
```

Parameters

421 422
| Attribute       | Type           | Required | Description                                                                                                      |
|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
423
| `id`            | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
424 425
| `job_id  `      | integer        | yes      | The unique job identifier.                                                                                       |
| `artifact_path` | string         | yes      | Path to a file inside the artifacts archive.                                                                     |
426 427 428

Example request:

429
```sh
430
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"
431 432
```

433
Possible response status codes:
434 435 436 437 438 439 440

| Status    | Description                          |
|-----------|--------------------------------------|
| 200       | Sends a single artifact file         |
| 400       | Invalid path provided                |
| 404       | Build not found or no file/artifacts |

441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456
## Download a single artifact file from specific tag or branch

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23538) in GitLab 11.5.

Download a single artifact file from a specific tag or branch from within the
job's artifacts archive. The file is extracted from the archive and streamed to
the client.

```
GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name
```

Parameters:

| Attribute       | Type           | Required | Description                                                                                                      |
|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
457
| `id`            | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
458 459 460 461 462 463 464
| `ref_name`      | string         | yes      | Branch or tag name in repository. HEAD or SHA references are not supported.                                      |
| `artifact_path` | string         | yes      | Path to a file inside the artifacts archive.                                                                     |
| `job`           | string         | yes      | The name of the job.                                                                                             |

Example request:

```sh
465
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/raw/some/release/file.pdf?job=pdf"
466 467 468 469 470 471 472 473 474 475
```

Possible response status codes:

| Status    | Description                          |
|-----------|--------------------------------------|
| 200       | Sends a single artifact file         |
| 400       | Invalid path provided                |
| 404       | Build not found or no file/artifacts |

476 477
## Get a trace file

478
Get a trace of a specific job of a project
479 480

```
481
GET /projects/:id/jobs/:job_id/trace
482 483
```

484 485
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
486 487
| id        | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| job_id    | integer        | yes      | ID of a job.                                                                                                 |
488

489
```sh
490
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace"
491 492
```

493
Possible response status codes:
494 495 496 497 498 499

| Status    | Description                       |
|-----------|-----------------------------------|
| 200       | Serves the trace file             |
| 404       | Build not found or no trace file  |

500
## Cancel a job
Tomasz Maczukin's avatar
Tomasz Maczukin committed
501

502
Cancel a single job of a project
Tomasz Maczukin's avatar
Tomasz Maczukin committed
503 504

```
505
POST /projects/:id/jobs/:job_id/cancel
Tomasz Maczukin's avatar
Tomasz Maczukin committed
506 507
```

508 509
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
510 511
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
512

513
```sh
514
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel"
515
```
Tomasz Maczukin's avatar
Tomasz Maczukin committed
516

Tomasz Maczukin's avatar
Tomasz Maczukin committed
517
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
518 519 520

```json
{
521 522 523 524 525 526 527 528 529 530 531
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "created_at": "2016-01-11T10:13:33.506Z",
532 533 534
  "started_at": "2016-01-11T10:14:09.526Z",
  "finished_at": null,
  "duration": 8,
535
  "id": 42,
536 537
  "name": "rubocop",
  "ref": "master",
538
  "artifacts": [],
539 540 541 542
  "runner": null,
  "stage": "test",
  "status": "canceled",
  "tag": false,
543
  "web_url": "https://example.com/foo/bar/-/jobs/42",
544
  "user": null
Tomasz Maczukin's avatar
Tomasz Maczukin committed
545 546 547
}
```

548
## Retry a job
Tomasz Maczukin's avatar
Tomasz Maczukin committed
549

550
Retry a single job of a project
Tomasz Maczukin's avatar
Tomasz Maczukin committed
551 552

```
553
POST /projects/:id/jobs/:job_id/retry
Tomasz Maczukin's avatar
Tomasz Maczukin committed
554 555
```

556 557
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
558 559
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
560

561
```sh
562
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry"
563
```
Tomasz Maczukin's avatar
Tomasz Maczukin committed
564

Tomasz Maczukin's avatar
Tomasz Maczukin committed
565
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
566 567 568

```json
{
569 570 571 572 573 574 575 576 577 578 579
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "created_at": "2016-01-11T10:13:33.506Z",
580
  "started_at": null,
581
  "finished_at": null,
582
  "duration": null,
583
  "id": 42,
584 585
  "name": "rubocop",
  "ref": "master",
586
  "artifacts": [],
587 588 589 590
  "runner": null,
  "stage": "test",
  "status": "pending",
  "tag": false,
591
  "web_url": "https://example.com/foo/bar/-/jobs/42",
592
  "user": null
Tomasz Maczukin's avatar
Tomasz Maczukin committed
593 594
}
```
595

596
## Erase a job
597

598
Erase a single job of a project (remove job artifacts and a job trace)
599 600

```
601
POST /projects/:id/jobs/:job_id/erase
602 603 604 605
```

Parameters

606 607
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
608 609
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
610 611 612

Example of request

613
```sh
614
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/erase"
615 616 617 618 619 620
```

Example of response

```json
{
621 622 623 624 625 626 627 628 629 630 631
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "download_url": null,
632
  "id": 42,
633 634
  "name": "rubocop",
  "ref": "master",
635
  "artifacts": [],
636 637 638 639 640
  "runner": null,
  "stage": "test",
  "created_at": "2016-01-11T10:13:33.506Z",
  "started_at": "2016-01-11T10:13:33.506Z",
  "finished_at": "2016-01-11T10:15:10.506Z",
641
  "duration": 97.0,
642 643
  "status": "failed",
  "tag": false,
644
  "web_url": "https://example.com/foo/bar/-/jobs/42",
645
  "user": null
646 647
}
```
648 649 650

## Keep artifacts

651
Prevents artifacts from being deleted when expiration is set.
652 653

```
654
POST /projects/:id/jobs/:job_id/artifacts/keep
655 656 657 658
```

Parameters

659 660
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
661 662
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
663

664
Example request:
665

666
```sh
667
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep"
668 669
```

670
Example response:
671 672 673

```json
{
674 675 676 677 678 679 680 681 682 683 684
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "download_url": null,
685
  "id": 42,
686 687
  "name": "rubocop",
  "ref": "master",
688
  "artifacts": [],
689 690 691 692 693
  "runner": null,
  "stage": "test",
  "created_at": "2016-01-11T10:13:33.506Z",
  "started_at": "2016-01-11T10:13:33.506Z",
  "finished_at": "2016-01-11T10:15:10.506Z",
694
  "duration": 97.0,
695 696
  "status": "failed",
  "tag": false,
697
  "web_url": "https://example.com/foo/bar/-/jobs/42",
698
  "user": null
699 700
}
```
Z.J. van de Weg's avatar
Z.J. van de Weg committed
701

702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728
## Delete artifacts

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25522) in GitLab 11.9.

Delete artifacts of a job.

```
DELETE /projects/:id/jobs/:job_id/artifacts
```

| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `job_id`  | integer        | yes      | ID of a job.                                                                |


Example request:

```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts"
```

NOTE: **Note:**
At least Maintainer role is required to delete artifacts.

If the artifacts were deleted successfully, a response with status `204 No Content` is returned.

729
## Play a job
Z.J. van de Weg's avatar
Z.J. van de Weg committed
730

731
Triggers a manual action to start a job.
Z.J. van de Weg's avatar
Z.J. van de Weg committed
732 733

```
734
POST /projects/:id/jobs/:job_id/play
Z.J. van de Weg's avatar
Z.J. van de Weg committed
735 736
```

737 738
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
739 740
| `id`      | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | ID of a job.                                                                                                 |
Z.J. van de Weg's avatar
Z.J. van de Weg committed
741

742
```sh
743
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/play"
Z.J. van de Weg's avatar
Z.J. van de Weg committed
744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760
```

Example of response

```json
{
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "created_at": "2016-01-11T10:13:33.506Z",
761
  "started_at": null,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
762
  "finished_at": null,
763
  "duration": null,
764
  "id": 42,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
765 766
  "name": "rubocop",
  "ref": "master",
767
  "artifacts": [],
Z.J. van de Weg's avatar
Z.J. van de Weg committed
768 769 770 771
  "runner": null,
  "stage": "test",
  "status": "started",
  "tag": false,
772
  "web_url": "https://example.com/foo/bar/-/jobs/42",
Z.J. van de Weg's avatar
Z.J. van de Weg committed
773 774 775
  "user": null
}
```