debian-mirror-gitlab/doc/api/pipelines.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

446 lines
14 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Verify
2021-09-04 01:27:46 +05:30
group: Pipeline Execution
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-24 23:57:45 +05:30
---
2021-09-04 01:27:46 +05:30
# Pipelines API **(FREE)**
2016-09-13 17:45:13 +05:30
2020-05-24 23:13:21 +05:30
## Pipelines pagination
By default, `GET` requests return 20 results at a time because the API results
are paginated.
2021-09-30 23:02:18 +05:30
Read more on [pagination](index.md#pagination).
2020-05-24 23:13:21 +05:30
2016-09-13 17:45:13 +05:30
## List project pipelines
2022-01-26 12:08:38 +05:30
> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
2021-12-11 22:18:48 +05:30
List pipelines in a project. Child pipelines are not included in the results,
but you can [get child pipeline](pipelines.md#get-a-single-pipeline) individually.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-13 17:45:13 +05:30
GET /projects/:id/pipelines
```
| Attribute | Type | Required | Description |
|-----------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2017-08-17 22:00:37 +05:30
| `scope` | string | no | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` |
2020-10-24 23:57:45 +05:30
| `status` | string | no | The status of pipelines, one of: `created`, `waiting_for_resource`, `preparing`, `pending`, `running`, `success`, `failed`, `canceled`, `skipped`, `manual`, `scheduled` |
2021-11-11 11:23:49 +05:30
| `source` | string | no | In [GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325439), how the pipeline was triggered, one of: `push`, `web`, `trigger`, `schedule`, `api`, `external`, `pipeline`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, `ondemand_dast_scan`, or `ondemand_dast_validation`. |
2017-08-17 22:00:37 +05:30
| `ref` | string | no | The ref of pipelines |
2020-04-22 19:07:51 +05:30
| `sha` | string | no | The SHA of pipelines |
2017-08-17 22:00:37 +05:30
| `yaml_errors`| boolean | no | Returns pipelines with invalid configurations |
| `username`| string | no | The username of the user who triggered pipelines |
2021-01-29 00:20:46 +05:30
| `updated_after` | datetime | no | Return pipelines updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `updated_before` | datetime | no | Return pipelines updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
2020-01-01 13:55:28 +05:30
| `order_by`| string | no | Order pipelines by `id`, `status`, `ref`, `updated_at` or `user_id` (default: `id`) |
2017-08-17 22:00:37 +05:30
| `sort` | string | no | Sort pipelines in `asc` or `desc` order (default: `desc`) |
2016-09-13 17:45:13 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines"
2016-09-13 17:45:13 +05:30
```
Example of response
```json
[
{
"id": 47,
2021-10-27 15:23:28 +05:30
"iid": 12,
2021-04-17 20:07:23 +05:30
"project_id": 1,
2016-09-13 17:45:13 +05:30
"status": "pending",
2022-01-26 12:08:38 +05:30
"source": "push",
2016-09-13 17:45:13 +05:30
"ref": "new-pipeline",
2018-11-18 11:00:15 +05:30
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
2019-12-21 20:55:43 +05:30
"web_url": "https://example.com/foo/bar/pipelines/47",
"created_at": "2016-08-11T11:28:34.085Z",
2021-06-08 01:23:25 +05:30
"updated_at": "2016-08-11T11:32:35.169Z"
2016-09-13 17:45:13 +05:30
},
{
"id": 48,
2021-10-27 15:23:28 +05:30
"iid": 13,
2021-04-17 20:07:23 +05:30
"project_id": 1,
2016-09-13 17:45:13 +05:30
"status": "pending",
2022-01-26 12:08:38 +05:30
"source": "web",
2016-09-13 17:45:13 +05:30
"ref": "new-pipeline",
2018-11-18 11:00:15 +05:30
"sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a",
2019-12-21 20:55:43 +05:30
"web_url": "https://example.com/foo/bar/pipelines/48",
"created_at": "2016-08-12T10:06:04.561Z",
2021-06-08 01:23:25 +05:30
"updated_at": "2016-08-12T10:09:56.223Z"
2016-09-13 17:45:13 +05:30
}
]
```
## Get a single pipeline
2022-01-26 12:08:38 +05:30
> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
2021-12-11 22:18:48 +05:30
Get one pipeline from a project.
You can also get a single [child pipeline](../ci/pipelines/parent_child_pipelines.md).
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36494) in GitLab 13.3.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-13 17:45:13 +05:30
GET /projects/:id/pipelines/:pipeline_id
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-09-13 17:45:13 +05:30
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"
2016-09-13 17:45:13 +05:30
```
Example of response
```json
{
"id": 46,
2021-10-27 15:23:28 +05:30
"iid": 11,
2021-04-17 20:07:23 +05:30
"project_id": 1,
2016-09-13 17:45:13 +05:30
"status": "success",
2021-09-04 01:27:46 +05:30
"ref": "main",
2016-09-13 17:45:13 +05:30
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/root"
2016-09-13 17:45:13 +05:30
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
2021-06-08 01:23:25 +05:30
"duration": 123.65,
"queued_duration": 0.010,
2018-11-18 11:00:15 +05:30
"coverage": "30.0",
"web_url": "https://example.com/foo/bar/pipelines/46"
2016-09-13 17:45:13 +05:30
}
```
2019-07-31 22:56:46 +05:30
### Get variables of a pipeline
2020-04-08 14:13:33 +05:30
```plaintext
2019-07-31 22:56:46 +05:30
GET /projects/:id/pipelines/:pipeline_id/variables
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-07-31 22:56:46 +05:30
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-04-08 14:13:33 +05:30
```shell
2019-07-31 22:56:46 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/variables"
```
Example of response
```json
[
{
"key": "RUN_NIGHTLY_BUILD",
"variable_type": "env_var",
"value": "true"
},
{
"key": "foo",
"value": "bar"
}
]
```
2020-05-24 23:13:21 +05:30
### Get a pipeline's test report
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202525) in GitLab 13.0.
2021-02-22 17:27:13 +05:30
NOTE:
2022-07-23 23:45:48 +05:30
This API route is part of the [Unit test report](../ci/testing/unit_test_reports.md) feature.
2020-05-24 23:13:21 +05:30
```plaintext
GET /projects/:id/pipelines/:pipeline_id/test_report
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_id` | integer | yes | The ID of a pipeline |
Sample request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/test_report"
```
Sample response:
```json
{
"total_time": 5,
"total_count": 1,
"success_count": 1,
"failed_count": 0,
"skipped_count": 0,
"error_count": 0,
"test_suites": [
{
"name": "Secure",
"total_time": 5,
"total_count": 1,
"success_count": 1,
"failed_count": 0,
"skipped_count": 0,
"error_count": 0,
"test_cases": [
{
"status": "success",
"name": "Security Reports can create an auto-remediation MR",
"classname": "vulnerability_management_spec",
"execution_time": 5,
"system_output": null,
"stack_trace": null
}
]
}
]
}
```
2021-10-27 15:23:28 +05:30
### Get a pipeline's test report summary
2021-11-11 11:23:49 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65471) in GitLab 14.2.
2021-10-27 15:23:28 +05:30
NOTE:
2022-07-23 23:45:48 +05:30
This API route is part of the [Unit test report](../ci/testing/unit_test_reports.md) feature.
2021-10-27 15:23:28 +05:30
```plaintext
GET /projects/:id/pipelines/:pipeline_id/test_report_summary
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `pipeline_id` | integer | yes | The ID of a pipeline |
Sample request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/test_report_summary"
```
Sample response:
```json
{
"total": {
"time": 1904,
"count": 3363,
"success": 3351,
"failed": 0,
"skipped": 12,
"error": 0,
"suite_error": null
},
"test_suites": [
{
"name": "test",
"total_time": 1904,
"total_count": 3363,
"success_count": 3351,
"failed_count": 0,
"skipped_count": 12,
"error_count": 0,
"build_ids": [
66004
],
"suite_error": null
}
]
}
```
2017-08-17 22:00:37 +05:30
## Create a new pipeline
2022-01-26 12:08:38 +05:30
> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/pipeline
```
2019-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
|-------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2022-03-02 08:16:31 +05:30
| `ref` | string | yes | The branch or tag to run the pipeline on. |
2022-01-26 12:08:38 +05:30
| `variables` | array | no | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. |
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main"
2017-08-17 22:00:37 +05:30
```
Example of response
```json
{
"id": 61,
2021-10-27 15:23:28 +05:30
"iid": 21,
2021-04-17 20:07:23 +05:30
"project_id": 1,
2017-08-17 22:00:37 +05:30
"sha": "384c444e840a515b23f21915ee5766b87068a70d",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-08-17 22:00:37 +05:30
"status": "pending",
"before_sha": "0000000000000000000000000000000000000000",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://localhost:3000/root"
},
"created_at": "2016-11-04T09:36:13.747Z",
"updated_at": "2016-11-04T09:36:13.977Z",
"started_at": null,
"finished_at": null,
"committed_at": null,
"duration": null,
2021-06-08 01:23:25 +05:30
"queued_duration": 0.010,
2018-11-18 11:00:15 +05:30
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/61"
2017-08-17 22:00:37 +05:30
}
```
## Retry jobs in a pipeline
2016-09-13 17:45:13 +05:30
2022-01-26 12:08:38 +05:30
> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6.
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-13 17:45:13 +05:30
POST /projects/:id/pipelines/:pipeline_id/retry
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-09-13 17:45:13 +05:30
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/retry"
2016-09-13 17:45:13 +05:30
```
Response:
```json
{
"id": 46,
2021-10-27 15:23:28 +05:30
"iid": 11,
2021-04-17 20:07:23 +05:30
"project_id": 1,
2016-09-13 17:45:13 +05:30
"status": "pending",
2021-09-04 01:27:46 +05:30
"ref": "main",
2016-09-13 17:45:13 +05:30
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/root"
2016-09-13 17:45:13 +05:30
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
2017-08-17 22:00:37 +05:30
"duration": null,
2021-06-08 01:23:25 +05:30
"queued_duration": 0.010,
2018-11-18 11:00:15 +05:30
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/46"
2016-09-13 17:45:13 +05:30
}
```
2020-05-24 23:13:21 +05:30
## Cancel a pipeline's jobs
2016-09-13 17:45:13 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-09-13 17:45:13 +05:30
POST /projects/:id/pipelines/:pipeline_id/cancel
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-09-13 17:45:13 +05:30
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/cancel"
2016-09-13 17:45:13 +05:30
```
Response:
```json
{
"id": 46,
2021-10-27 15:23:28 +05:30
"iid": 11,
2021-04-17 20:07:23 +05:30
"project_id": 1,
2016-09-13 17:45:13 +05:30
"status": "canceled",
2021-09-04 01:27:46 +05:30
"ref": "main",
2016-09-13 17:45:13 +05:30
"sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
"tag": false,
"yaml_errors": null,
"user": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/root"
2016-09-13 17:45:13 +05:30
},
"created_at": "2016-08-11T11:28:34.085Z",
"updated_at": "2016-08-11T11:32:35.169Z",
"started_at": null,
"finished_at": "2016-08-11T11:32:35.145Z",
"committed_at": null,
2017-08-17 22:00:37 +05:30
"duration": null,
2021-06-08 01:23:25 +05:30
"queued_duration": 0.010,
2018-11-18 11:00:15 +05:30
"coverage": null,
"web_url": "https://example.com/foo/bar/pipelines/46"
2016-09-13 17:45:13 +05:30
}
```
2019-02-15 15:39:39 +05:30
## Delete a pipeline
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22988) in GitLab 11.6.
2019-02-15 15:39:39 +05:30
2022-07-23 23:45:48 +05:30
Deleting a pipeline expires all pipeline caches, and deletes all immediately
related objects, such as builds, logs, artifacts, and triggers.
**This action cannot be undone.**
Deleting a pipeline does not automatically delete its
[child pipelines](../ci/pipelines/parent_child_pipelines.md).
See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39503)
for details.
2020-04-08 14:13:33 +05:30
```plaintext
2019-02-15 15:39:39 +05:30
DELETE /projects/:id/pipelines/:pipeline_id
```
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2019-02-15 15:39:39 +05:30
| `pipeline_id` | integer | yes | The ID of a pipeline |
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"
```