347.md

# Pipelines API

> 原文：[https://docs.gitlab.com/ee/api/pipelines.html](https://docs.gitlab.com/ee/api/pipelines.html)

*   [Single Pipeline Requests](#single-pipeline-requests)
*   [Pipelines pagination](#pipelines-pagination)
*   [List project pipelines](#list-project-pipelines)
*   [Get a single pipeline](#get-a-single-pipeline)
    *   [Get variables of a pipeline](#get-variables-of-a-pipeline)
    *   [Get a pipeline’s test report](#get-a-pipelines-test-report)
*   [Create a new pipeline](#create-a-new-pipeline)
*   [Retry jobs in a pipeline](#retry-jobs-in-a-pipeline)
*   [Cancel a pipeline’s jobs](#cancel-a-pipelines-jobs)
*   [Delete a pipeline](#delete-a-pipeline)

# Pipelines API[](#pipelines-api "Permalink")

## Single Pipeline Requests[](#single-pipeline-requests "Permalink")

在 GitLab 13.2 中[引入](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36494) .

请求有关单个管道的信息的端点返回任何管道的数据. 在 13.2 之前， [对子管道的](../ci/parent_child_pipelines.html)请求返回了 404 错误.

## Pipelines pagination[](#pipelines-pagination "Permalink")

默认情况下，因为 API 结果是分页的，所以`GET`请求一次返回 20 个结果.

阅读有关[分页的](README.html#pagination)更多信息.

## List project pipelines[](#list-project-pipelines "Permalink")

在 GitLab 8.11 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837)

```
GET /projects/:id/pipelines 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `scope` | string | no | 管道的范围，其中之一： `running` ， `pending` ， `finished` ， `branches` ， `tags` |
| `status` | string | no | 管道的状态，其中之一： `running` ， `pending` ， `success` ， `failed` ， `canceled` ， `skipped` ， `created` ， `manual` |
| `ref` | string | no | 管道的引用 |
| `sha` | string | no | 管道的 SHA |
| `yaml_errors` | boolean | no | 返回无效配置的管道 |
| `name` | string | no | 触发管道的用户名 |
| `username` | string | no | 触发管道的用户的用户名 |
| `updated_after` | datetime | no | 返回在指定日期之后更新的管道. 格式：ISO 8601 YYYY-MM-DDTHH：MM：SSZ |
| `updated_before` | datetime | no | 返回在指定日期之前更新的管道. 格式：ISO 8601 YYYY-MM-DDTHH：MM：SSZ |
| `order_by` | string | no | 按`id` ， `status` ， `ref` ， `updated_at`或`user_id` `updated_at`管道（默认值： `id` ） |
| `sort` | string | no | 按`asc`或`desc`顺序对管道进行排序（默认值： `desc` ） |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines" 
```

回应范例

```
[  {  "id":  47,  "status":  "pending",  "ref":  "new-pipeline",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "web_url":  "https://example.com/foo/bar/pipelines/47",  "created_at":  "2016-08-11T11:28:34.085Z",  "updated_at":  "2016-08-11T11:32:35.169Z",  },  {  "id":  48,  "status":  "pending",  "ref":  "new-pipeline",  "sha":  "eb94b618fb5865b26e80fdd8ae531b7a63ad851a",  "web_url":  "https://example.com/foo/bar/pipelines/48",  "created_at":  "2016-08-12T10:06:04.561Z",  "updated_at":  "2016-08-12T10:09:56.223Z",  }  ] 
```

## Get a single pipeline[](#get-a-single-pipeline "Permalink")

在 GitLab 8.11 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837)

```
GET /projects/:id/pipelines/:pipeline_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `pipeline_id` | integer | yes | 管道的 ID |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46" 
```

回应范例

```
{  "id":  46,  "status":  "success",  "ref":  "master",  "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",  "web_url":  "http://localhost:3000/root"  },  "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,  "duration":  null,  "coverage":  "30.0",  "web_url":  "https://example.com/foo/bar/pipelines/46"  } 
```

### Get variables of a pipeline[](#get-variables-of-a-pipeline "Permalink")

```
GET /projects/:id/pipelines/:pipeline_id/variables 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `pipeline_id` | integer | yes | 管道的 ID |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/variables" 
```

回应范例

```
[  {  "key":  "RUN_NIGHTLY_BUILD",  "variable_type":  "env_var",  "value":  "true"  },  {  "key":  "foo",  "value":  "bar"  }  ] 
```

### Get a pipeline’s test report[](#get-a-pipelines-test-report "Permalink")

在 GitLab 13.0 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/202525) .

**警告：**此 API 路由是[JUnit 测试报告](../ci/junit_test_reports.html)功能的一部分. 它受一个[功能标志](../development/feature_flags/index.html)保护，该[功能标志](../development/feature_flags/index.html)由于非常大的数据集的性能问题而被**禁用** .

```
GET /projects/:id/pipelines/:pipeline_id/test_report 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `pipeline_id` | integer | yes | The ID of a pipeline |

样品要求：

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/test_report" 
```

样本回复：

```
{  "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  }  ]  }  ]  } 
```

## Create a new pipeline[](#create-a-new-pipeline "Permalink")

在 GitLab 8.14 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7209)

```
POST /projects/:id/pipeline 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `ref` | string | yes | 提交参考 |
| `variables` | array | no | 包含管道中可用变量的数组，与结构`[{ 'key' => 'UPLOAD_TO_S3', 'variable_type' => 'file', 'value' => 'true' }]`匹配 |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master" 
```

回应范例

```
{  "id":  61,  "sha":  "384c444e840a515b23f21915ee5766b87068a70d",  "ref":  "master",  "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,  "coverage":  null,  "web_url":  "https://example.com/foo/bar/pipelines/61"  } 
```

## Retry jobs in a pipeline[](#retry-jobs-in-a-pipeline "Permalink")

在 GitLab 8.11 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837)

```
POST /projects/:id/pipelines/:pipeline_id/retry 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `pipeline_id` | integer | yes | 管道的 ID |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/retry" 
```

Response:

```
{  "id":  46,  "status":  "pending",  "ref":  "master",  "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",  "web_url":  "http://localhost:3000/root"  },  "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,  "duration":  null,  "coverage":  null,  "web_url":  "https://example.com/foo/bar/pipelines/46"  } 
```

## Cancel a pipeline’s jobs[](#cancel-a-pipelines-jobs "Permalink")

在 GitLab 8.11 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837)

```
POST /projects/:id/pipelines/:pipeline_id/cancel 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `pipeline_id` | integer | yes | 管道的 ID |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/cancel" 
```

Response:

```
{  "id":  46,  "status":  "canceled",  "ref":  "master",  "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",  "web_url":  "http://localhost:3000/root"  },  "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,  "duration":  null,  "coverage":  null,  "web_url":  "https://example.com/foo/bar/pipelines/46"  } 
```

## Delete a pipeline[](#delete-a-pipeline "Permalink")

在 GitLab 11.6 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22988) .

```
DELETE /projects/:id/pipelines/:pipeline_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `pipeline_id` | integer | yes | 管道的 ID |

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