流水线 API

流水线分页机制

在默认情况下，GET 请求每次只返回 20 条结果，这是因为我们采用了分页机制。

阅读分页，了解更多详情。

列出项目流水线

响应中的 iid 引入于 14.6 版本。

列出项目中的流水线。 结果中不包含子流水线，但您可以单独获取子流水线。 

GET /projects/:id/pipelines
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
scope string no 流水线的范围，可接受的值有 running、pending、finished、branches、tags
status string no 流水线的状态，可接受的值有 created、waiting_for_resource、preparing、pending、running、success、failed、canceled、skipped、manual、scheduled
source string no 引入于 14.3 版本。流水线触发方式，可接受的值有 push、web、trigger、schedule、api、external、pipeline、chat、webide、merge_request_event、external_pull_request_event、parent_pipeline、ondemand_dast_scan 或者 ondemand_dast_validation
ref string no 流水线的 ref
sha string no 流水线的 SHA
yaml_errors boolean no 返回具有无效配置的流水线
username string no 触发流水线用户的用户名
updated_after datetime no 对于给定的时间戳，返回不早于该时间更新的流水线。时间戳应符合 ISO 8601 格式（2019-03-15T08:00:00Z）
updated_before datetime no 对于给定的时间戳，返回不晚于该时间更新的流水线。时间戳应符合 ISO 8601 格式（2019-03-15T08:00:00Z）
order_by string no 按照 id、status、ref、updated_at 或者 user_id（默认：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,
    "iid": 12,
    "project_id": 1,
    "status": "pending",
    "source": "push",
    "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,
    "iid": 13,
    "project_id": 1,
    "status": "pending",
    "source": "web",
    "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"
  }
]

获取单个流水线

响应中的 iid 引入于 14.6 版本。

您也可以获取单个子流水线)。 引入于 13.3 版本。 

GET /projects/:id/pipelines/:pipeline_id
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
pipeline_id integer yes 流水线的 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"

响应示例： 

{
  "id": 46,
  "iid": 11,
  "project_id": 1,
  "status": "success",
  "ref": "main",
  "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": 123.65,
  "queued_duration": 0.010,
  "coverage": "30.0",
  "web_url": "https://example.com/foo/bar/pipelines/46"
}

获取流水线的变量 

GET /projects/:id/pipelines/:pipeline_id/variables
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
pipeline_id integer yes 流水线的 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/variables"

Example of response 

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

获取流水线的测试报告

引入于 13.0 版本。

note此 API 路由已经成为单元测试报告特性中的一部分。
GET /projects/:id/pipelines/:pipeline_id/test_report
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
pipeline_id integer yes 流水线的 ID

请求示例： 

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
        }
      ]
    }
  ]
}

获取流水线的测试报告摘要

引入于 14.2 版本。

note此 API 路由已经成为单元测试报告特性中的一部分。
GET /projects/:id/pipelines/:pipeline_id/test_report_summary
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
pipeline_id integer yes 流水线的 ID

请求示例： 

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

响应示例： 

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

创建新的流水线

响应中的 iid 引入于 14.6 版本。 

POST /projects/:id/pipeline
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
ref string yes 流水线执行使用的分支或标签
variables array no 包含流水线中可用变量的哈希数组，匹配结构 [{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value' : 'true' }, {'key': 'TEST', 'value': '测试变量'}]。如果排除了 variable_type，则默认为 env_var。 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main"

响应示例： 

{
  "id": 61,
  "iid": 21,
  "project_id": 1,
  "sha": "384c444e840a515b23f21915ee5766b87068a70d",
  "ref": "main",
  "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,
  "queued_duration": 0.010,
  "coverage": null,
  "web_url": "https://example.com/foo/bar/pipelines/61"
}

重试流水线中的作业

响应中的 iid 引入于 14.6 版本。 

POST /projects/:id/pipelines/:pipeline_id/retry
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
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"

响应示例： 

{
  "id": 46,
  "iid": 11,
  "project_id": 1,
  "status": "pending",
  "ref": "main",
  "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,
  "queued_duration": 0.010,
  "coverage": null,
  "web_url": "https://example.com/foo/bar/pipelines/46"
}

取消流水线中的作业 

POST /projects/:id/pipelines/:pipeline_id/cancel
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
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"

响应示例： 

{
  "id": 46,
  "iid": 11,
  "project_id": 1,
  "status": "canceled",
  "ref": "main",
  "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,
  "queued_duration": 0.010,
  "coverage": null,
  "web_url": "https://example.com/foo/bar/pipelines/46"
}

删除流水线

引入于 11.6 版本。

删除流水线会使所有流水线缓存过期，并立即删除所有相关对象，包括构建、日志、产物和触发器。 此操作无法撤消。

删除流水线不会自动删除其子流水线。 

DELETE /projects/:id/pipelines/:pipeline_id
参数 类型 是否必需 描述
id integer/string yes 经过身份验证的用户拥有的项目 ID 或经过 URL 编码处理的路径
pipeline_id integer yes 流水线的 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"