jobs.md 31.6 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. Jobs are sorted in descending order of their IDs.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
6
7

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

Steve Azzopardi's avatar
Steve Azzopardi committed
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.                                                                                               |
Steve Azzopardi's avatar
Steve Azzopardi committed
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
```shell
17
curl --globoff --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,
35
    "allow_failure": false,
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
    "created_at": "2015-12-24T15:51:21.802Z",
    "started_at": "2015-12-24T17:54:27.722Z",
    "finished_at": "2015-12-24T17:54:27.895Z",
    "duration": 0.173,
    "artifacts_file": {
      "filename": "artifacts.zip",
      "size": 1000
    },
    "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"}
    ],
    "artifacts_expire_at": "2016-01-23T17:54:27.895Z",
    "id": 7,
    "name": "teaspoon",
53
54
55
56
57
58
59
    "pipeline": {
      "id": 6,
      "ref": "master",
      "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "status": "pending"
    },
    "ref": "master",
60
    "artifacts": [],
61
62
63
64
    "runner": null,
    "stage": "test",
    "status": "failed",
    "tag": false,
65
    "web_url": "https://example.com/foo/bar/-/jobs/7",
66
67
68
69
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
70
71
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
72
      "web_url": "http://gitlab.dev/root",
73
74
75
      "created_at": "2015-12-21T13:14:24.077Z",
      "bio": null,
      "location": null,
76
      "public_email": "",
77
78
79
80
81
      "skype": "",
      "linkedin": "",
      "twitter": "",
      "website_url": "",
      "organization": ""
82
83
84
85
86
87
88
89
90
91
92
93
94
    }
  },
  {
    "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,
95
    "allow_failure": false,
96
97
98
99
100
101
102
    "created_at": "2015-12-24T15:51:21.727Z",
    "started_at": "2015-12-24T17:54:24.729Z",
    "finished_at": "2015-12-24T17:54:24.921Z",
    "duration": 0.192,
    "artifacts_expire_at": "2016-01-23T17:54:24.921Z",
    "id": 6,
    "name": "rspec:other",
103
104
105
106
107
108
109
    "pipeline": {
      "id": 6,
      "ref": "master",
      "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
      "status": "pending"
    },
    "ref": "master",
110
    "artifacts": [],
111
112
113
114
    "runner": null,
    "stage": "test",
    "status": "failed",
    "tag": false,
115
    "web_url": "https://example.com/foo/bar/-/jobs/6",
116
117
118
119
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
120
121
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
122
      "web_url": "http://gitlab.dev/root",
123
124
125
      "created_at": "2015-12-21T13:14:24.077Z",
      "bio": null,
      "location": null,
126
      "public_email": "",
127
128
129
130
131
      "skype": "",
      "linkedin": "",
      "twitter": "",
      "website_url": "",
      "organization": ""
132
133
134
135
136
137
138
139
140
141
    }
  }
]
```

## List pipeline jobs

Get a list of jobs for a pipeline.

```
142
GET /projects/:id/pipelines/:pipeline_id/jobs
143
144
```

Steve Azzopardi's avatar
Steve Azzopardi committed
145
146
| Attribute     | Type                           | Required | Description                                                                                                                                                                                                    |
|---------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
147
148
| `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.                                                                                                                                                                                          |
Steve Azzopardi's avatar
Steve Azzopardi committed
149
| `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. |
150

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

Example of response

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

272
## Get a single job
Tomasz Maczukin's avatar
Tomasz Maczukin committed
273

274
Get a single job of a project
Tomasz Maczukin's avatar
Tomasz Maczukin committed
275
276

```
277
GET /projects/:id/jobs/:job_id
Tomasz Maczukin's avatar
Tomasz Maczukin committed
278
279
```

Steve Azzopardi's avatar
Steve Azzopardi committed
280
281
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
282
283
| `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.                                                                                                 |
284

285
```shell
286
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8"
287
288
```

Tomasz Maczukin's avatar
Tomasz Maczukin committed
289
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
290
291
292

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

344
## Get job artifacts
345

346
> **Notes**:
347
>
348
> - [Introduced][ce-2893] in GitLab 8.5.
349
350
> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
>   in [GitLab Premium][ee] 9.5.
351

352
Get the job's artifacts zipped archive of a project.
353
354

```
355
GET /projects/:id/jobs/:job_id/artifacts
356
357
```

358
359
360
361
| Attribute   | Type           | Required | Description                                                                                                                                     |
|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `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.                                                                                                                                |
362
| `job_token` **(PREMIUM)** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
363

364
Example request using the `PRIVATE-TOKEN` header:
365

366
```shell
367
curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"
368
369
```

370
To use this in a [`script` definition](../ci/yaml/README.md#script) inside
371
`.gitlab-ci.yml` **(PREMIUM)**, you can use either:
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394

- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
  For example, the following job will download the artifacts of the job with ID
  `42`. Note that the command is wrapped into single quotes since it contains a
  colon (`:`):

  ```yaml
  artifact_download:
    stage: test
    script:
      - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"'
  ```

- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable.
  For example, the following job will download the artifacts of the job with ID `42`:

  ```yaml
  artifact_download:
    stage: test
    script:
      - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"'
  ```

Steve Azzopardi's avatar
Steve Azzopardi committed
395
Possible response status codes:
396
397
398

| Status    | Description                     |
|-----------|---------------------------------|
399
400
| 200       | Serves the artifacts file.      |
| 404       | Build not found or no artifacts.|
401

402
[ce-2893]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2893
403

404
## Download the artifacts archive
405

406
> **Notes**:
407
>
408
> - [Introduced][ce-5347] in GitLab 8.10.
409
410
> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346]
>   in [GitLab Premium][ee] 9.5.
411

412
413
414
415
Download the artifacts zipped archive from the latest successful pipeline for
the given reference name and job, provided the job finished successfully. This
is the same as [getting the job's artifacts](#get-job-artifacts), but by
defining the job's name instead of its ID.
416
417

```
418
GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
419
420
421
422
```

Parameters

423
424
425
426
427
| Attribute   | Type           | Required | Description                                                                                                                                     |
|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`        | integer/string | yes      | 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.                                                                                                                            |
428
| `job_token` **(PREMIUM)** | string         | no       | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
429

430
Example request using the `PRIVATE-TOKEN` header:
431

432
```shell
433
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test"
434
435
```

436
To use this in a [`script` definition](../ci/yaml/README.md#script) inside
437
`.gitlab-ci.yml` **(PREMIUM)**, you can use either:
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461

- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
  For example, the following job will download the artifacts of the `test` job
  of the `master` branch. Note that the command is wrapped into single quotes
  since it contains a colon (`:`):

  ```yaml
  artifact_download:
    stage: test
    script:
      - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test"'
  ```

- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable.
  For example, the following job will download the artifacts of the `test` job
  of the `master` branch:

  ```yaml
  artifact_download:
    stage: test
    script:
      - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"'
  ```

Steve Azzopardi's avatar
Steve Azzopardi committed
462
Possible response status codes:
463
464
465

| Status    | Description                     |
|-----------|---------------------------------|
466
467
| 200       | Serves the artifacts file.      |
| 404       | Build not found or no artifacts.|
468

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

471
## Download a single artifact file by job ID
472
473
474

> Introduced in GitLab 10.0

Steve Azzopardi's avatar
Steve Azzopardi committed
475
Download a single artifact file from a job with a specified ID from within
476
the job's artifacts zipped archive. The file is extracted from the archive and
Steve Azzopardi's avatar
Steve Azzopardi committed
477
streamed to the client.
478
479
480
481
482
483
484

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

Parameters

Steve Azzopardi's avatar
Steve Azzopardi committed
485
486
| Attribute       | Type           | Required | Description                                                                                                      |
|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
487
| `id`            | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
488
| `job_id`        | integer        | yes      | The unique job identifier.                                                                                       |
Steve Azzopardi's avatar
Steve Azzopardi committed
489
| `artifact_path` | string         | yes      | Path to a file inside the artifacts archive.                                                                     |
490
491
492

Example request:

493
```shell
494
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"
495
496
```

Steve Azzopardi's avatar
Steve Azzopardi committed
497
Possible response status codes:
498
499
500
501
502
503
504

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

505
506
## Download a single artifact file from specific tag or branch

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

509
510
511
Download a single artifact file for a specific job of the latest successful
pipeline for the given reference name from within the job's artifacts archive.
The file is extracted from the archive and streamed to the client.
512
513
514
515
516
517
518
519
520

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

Parameters:

| Attribute       | Type           | Required | Description                                                                                                      |
|-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
521
| `id`            | integer/string | yes      | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
522
523
524
525
526
527
| `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:

528
```shell
529
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/raw/some/release/file.pdf?job=pdf"
530
531
532
533
534
535
536
537
538
539
```

Possible response status codes:

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

540
## Get a log file
541

542
Get a log (trace) of a specific job of a project:
543
544

```
545
GET /projects/:id/jobs/:job_id/trace
546
547
```

Steve Azzopardi's avatar
Steve Azzopardi committed
548
549
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
550
551
| 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.                                                                                                 |
552

553
```shell
554
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace"
555
556
```

Steve Azzopardi's avatar
Steve Azzopardi committed
557
Possible response status codes:
558

559
560
561
562
| Status    | Description                   |
|-----------|-------------------------------|
| 200       | Serves the log file           |
| 404       | Job not found or no log file  |
563

564
## Cancel a job
Tomasz Maczukin's avatar
Tomasz Maczukin committed
565

566
Cancel a single job of a project
Tomasz Maczukin's avatar
Tomasz Maczukin committed
567
568

```
569
POST /projects/:id/jobs/:job_id/cancel
Tomasz Maczukin's avatar
Tomasz Maczukin committed
570
571
```

Steve Azzopardi's avatar
Steve Azzopardi committed
572
573
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
574
575
| `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.                                                                                                 |
576

577
```shell
578
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel"
579
```
Tomasz Maczukin's avatar
Tomasz Maczukin committed
580

Tomasz Maczukin's avatar
Tomasz Maczukin committed
581
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
582
583
584

```json
{
585
586
587
588
589
590
591
592
593
594
  "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,
595
  "allow_failure": false,
596
  "created_at": "2016-01-11T10:13:33.506Z",
597
598
599
  "started_at": "2016-01-11T10:14:09.526Z",
  "finished_at": null,
  "duration": 8,
600
  "id": 42,
601
602
  "name": "rubocop",
  "ref": "master",
603
  "artifacts": [],
604
605
606
607
  "runner": null,
  "stage": "test",
  "status": "canceled",
  "tag": false,
608
  "web_url": "https://example.com/foo/bar/-/jobs/42",
609
  "user": null
Tomasz Maczukin's avatar
Tomasz Maczukin committed
610
611
612
}
```

613
## Retry a job
Tomasz Maczukin's avatar
Tomasz Maczukin committed
614

615
Retry a single job of a project
Tomasz Maczukin's avatar
Tomasz Maczukin committed
616
617

```
618
POST /projects/:id/jobs/:job_id/retry
Tomasz Maczukin's avatar
Tomasz Maczukin committed
619
620
```

Steve Azzopardi's avatar
Steve Azzopardi committed
621
622
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
623
624
| `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.                                                                                                 |
625

626
```shell
627
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry"
628
```
Tomasz Maczukin's avatar
Tomasz Maczukin committed
629

Tomasz Maczukin's avatar
Tomasz Maczukin committed
630
Example of response
Tomasz Maczukin's avatar
Tomasz Maczukin committed
631
632
633

```json
{
634
635
636
637
638
639
640
641
642
643
  "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,
644
  "allow_failure": false,
645
  "created_at": "2016-01-11T10:13:33.506Z",
646
  "started_at": null,
647
  "finished_at": null,
648
  "duration": null,
649
  "id": 42,
650
651
  "name": "rubocop",
  "ref": "master",
652
  "artifacts": [],
653
654
655
656
  "runner": null,
  "stage": "test",
  "status": "pending",
  "tag": false,
657
  "web_url": "https://example.com/foo/bar/-/jobs/42",
658
  "user": null
Tomasz Maczukin's avatar
Tomasz Maczukin committed
659
660
}
```
661

662
## Erase a job
663

664
Erase a single job of a project (remove job artifacts and a job log)
665
666

```
667
POST /projects/:id/jobs/:job_id/erase
668
669
670
671
```

Parameters

Steve Azzopardi's avatar
Steve Azzopardi committed
672
673
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
674
675
| `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.                                                                                                 |
676
677
678

Example of request

679
```shell
680
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/erase"
681
682
683
684
685
686
```

Example of response

```json
{
687
688
689
690
691
692
693
694
695
696
  "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,
697
  "allow_failure": false,
698
  "download_url": null,
699
  "id": 42,
700
701
  "name": "rubocop",
  "ref": "master",
702
  "artifacts": [],
703
704
705
706
707
  "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",
708
  "duration": 97.0,
709
710
  "status": "failed",
  "tag": false,
711
  "web_url": "https://example.com/foo/bar/-/jobs/42",
712
  "user": null
713
714
}
```
715
716
717

## Keep artifacts

718
Prevents artifacts from being deleted when expiration is set.
719
720

```
721
POST /projects/:id/jobs/:job_id/artifacts/keep
722
723
724
725
```

Parameters

Steve Azzopardi's avatar
Steve Azzopardi committed
726
727
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
728
729
| `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.                                                                                                 |
730

731
Example request:
732

733
```shell
734
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep"
735
736
```

737
Example response:
738
739
740

```json
{
741
742
743
744
745
746
747
748
749
750
  "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,
751
  "allow_failure": false,
752
  "download_url": null,
753
  "id": 42,
754
755
  "name": "rubocop",
  "ref": "master",
756
  "artifacts": [],
757
758
759
760
761
  "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",
762
  "duration": 97.0,
763
764
  "status": "failed",
  "tag": false,
765
  "web_url": "https://example.com/foo/bar/-/jobs/42",
766
  "user": null
767
768
}
```
Z.J. van de Weg's avatar
Z.J. van de Weg committed
769

770
771
## Delete artifacts

772
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25522) in GitLab 11.9.
773
774
775
776
777
778
779
780
781
782
783
784
785
786

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:

787
```shell
788
789
790
791
792
793
794
795
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.

796
## Play a job
Z.J. van de Weg's avatar
Z.J. van de Weg committed
797

798
Triggers a manual action to start a job.
Z.J. van de Weg's avatar
Z.J. van de Weg committed
799
800

```
801
POST /projects/:id/jobs/:job_id/play
Z.J. van de Weg's avatar
Z.J. van de Weg committed
802
803
```

Steve Azzopardi's avatar
Steve Azzopardi committed
804
805
| Attribute | Type           | Required | Description                                                                                                      |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
806
807
| `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
808

809
```shell
810
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
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
```

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,
827
  "allow_failure": false,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
828
  "created_at": "2016-01-11T10:13:33.506Z",
829
  "started_at": null,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
830
  "finished_at": null,
831
  "duration": null,
832
  "id": 42,
Z.J. van de Weg's avatar
Z.J. van de Weg committed
833
834
  "name": "rubocop",
  "ref": "master",
835
  "artifacts": [],
Z.J. van de Weg's avatar
Z.J. van de Weg committed
836
837
838
839
  "runner": null,
  "stage": "test",
  "status": "started",
  "tag": false,
840
  "web_url": "https://example.com/foo/bar/-/jobs/42",
Z.J. van de Weg's avatar
Z.J. van de Weg committed
841
842
843
  "user": null
}
```
844
845

[ee]: https://about.gitlab.com/pricing/
846
[ee-2346]: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346
847
[triggers]: ../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium