jobs.md 26.8 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 13 14
| Attribute | Type                           | Required | Description                                                                                                                                                                                                    |
|-----------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string                 | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                                                                               |
| `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 145 146 147
| Attribute     | Type                           | Required | Description                                                                                                                                                                                                    |
|---------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`          | integer/string                 | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.                                                                                               |
| `pipeline_id` | integer                        | yes      | The ID of a pipeline.                                                                                                                                                                                          |
| `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 278 279
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | The 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 353 354
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | The 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 388 389 390
| Attribute  | Type           | Required | Description                                                                                                      |
|------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `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 423 424 425
| Attribute       | Type           | Required | Description                                                                                                      |
|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `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 457 458 459 460 461 462 463 464
## 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                                                                                                      |
|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`            | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `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 486 487
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| id        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| job_id    | integer        | yes      | The 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 510 511
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | The 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 558 559
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | The 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 608 609
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | The 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 661 662
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id`  | integer        | yes      | The 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
## Play a job
Z.J. van de Weg's avatar
Z.J. van de Weg committed
703

704
Triggers a manual action to start a job.
Z.J. van de Weg's avatar
Z.J. van de Weg committed
705 706

```
707
POST /projects/:id/jobs/:job_id/play
Z.J. van de Weg's avatar
Z.J. van de Weg committed
708 709
```

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

715
```sh
716
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
717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733
```

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",
734
  "started_at": null,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
735
  "finished_at": null,
736
  "duration": null,
737
  "id": 42,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
738 739
  "name": "rubocop",
  "ref": "master",
740
  "artifacts": [],
Z.J. van de Weg's avatar
Z.J. van de Weg committed
741 742 743 744
  "runner": null,
  "stage": "test",
  "status": "started",
  "tag": false,
745
  "web_url": "https://example.com/foo/bar/-/jobs/42",
Z.J. van de Weg's avatar
Z.J. van de Weg committed
746 747 748
  "user": null
}
```