{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

流水线分页

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

阅读更多关于 分页 的信息。

列出项目流水线

{{< history >}}

  • 响应中的 iid 在 极狐GitLab 14.6 引入。
  • 响应中的 name 在 极狐GitLab 15.11 引入，使用名为 pipeline_name_in_api 的功能标志 。默认禁用。
  • 请求中的 name 在 15.11 引入，使用名为 pipeline_name_search 的功能标志 。默认禁用。
  • 响应中的 name 在 极狐GitLab 16.3 GA。特性标志 pipeline_name_in_api 被移除。
  • 请求中的 name 在 极狐GitLab 16.9 GA。特性标志 pipeline_name_search 被移除。
  • 支持返回 source 设置为 parent_pipeline 的子流水线在 极狐GitLab 17.0 引入。

{{< /history >}}

列出项目中的流水线。

默认情况下，子流水线 不包含在结果中。要返回子流水线，将 source 设置为 parent_pipeline。

GET /projects/:id/pipelines
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
name string 否 返回指定名称的流水线。
order_by string 否 按 id、status、ref、updated_at 或 user_id 排序流水线（默认：id）
ref string 否 流水线的引用
scope string 否 流水线的范围之一：running、pending、finished、branches、tags
sha string 否 流水线的 SHA
sort string 否 按 asc 或 desc 顺序排序流水线（默认：desc）
source string 否 流水线来源。
status string 否 流水线的状态之一：created、waiting_for_resource、preparing、pending、running、success、failed、canceled、skipped、manual、scheduled
updated_after datetime 否 返回在指定日期之后更新的流水线。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
updated_before datetime 否 返回在指定日期之前更新的流水线。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
created_after datetime 否 返回在指定日期之后创建的流水线。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
created_before datetime 否 返回在指定日期之前创建的流水线。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
username string 否 触发流水线的用户的用户名
yaml_errors boolean 否 返回配置无效的流水线 
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",
    "name": "Build pipeline",
    "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",
    "name": "Build pipeline",
    "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"
  }
]

获取单个流水线

{{< history >}}

  • 响应中的 iid 在 极狐GitLab 14.6 引入。
  • 响应中的 name 在 极狐GitLab 15.11 引入，使用名为 pipeline_name_in_api 的功能标志 。默认禁用。
  • 响应中的 name 在 极狐GitLab 16.3 GA。特性标志 pipeline_name_in_api 被移除。

{{< /history >}}

从项目中获取一个流水线。

您还可以获取单个 子流水线。

GET /projects/:id/pipelines/:pipeline_id
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"

响应示例

{
  "id": 287,
  "iid": 144,
  "project_id": 21,
  "name": "Build pipeline",
  "sha": "50f0acb76a40e34a4ff304f7347dcc6587da8a14",
  "ref": "main",
  "status": "success",
  "source": "push",
  "created_at": "2022-09-21T01:05:07.200Z",
  "updated_at": "2022-09-21T01:05:50.185Z",
  "web_url": "http://127.0.0.1:3000/test-group/test-project/-/pipelines/287",
  "before_sha": "8a24fb3c5877a6d0b611ca41fc86edc174593e2b",
  "tag": false,
  "yaml_errors": null,
  "user": {
    "id": 1,
    "username": "root",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "http://127.0.0.1:3000/root"
  },
  "started_at": "2022-09-21T01:05:14.197Z",
  "finished_at": "2022-09-21T01:05:50.175Z",
  "committed_at": null,
  "duration": 34,
  "queued_duration": 6,
  "coverage": null,
  "detailed_status": {
    "icon": "status_success",
    "text": "passed",
    "label": "passed",
    "group": "success",
    "tooltip": "passed",
    "has_details": false,
    "details_path": "/test-group/test-project/-/pipelines/287",
    "illustration": null,
    "favicon": "/assets/ci_favicons/favicon_status_success-8451333011eee8ce9f2ab25dc487fe24a8758c694827a582f17f42b0a90446a2.png"
  }
}

获取最新的流水线

{{< history >}}

  • 响应中的 name 在 极狐GitLab 15.11 引入，使用名为 pipeline_name_in_api 的功能标志 。默认禁用。
  • 响应中的 name 在 极狐GitLab 16.3 GA。特性标志 pipeline_name_in_api 被移除。

{{< /history >}}

获取项目中特定引用上最新提交的最新流水线。如果提交不存在流水线，则返回 403 状态码。

GET /projects/:id/pipelines/latest
属性 类型 必需 描述
ref string 否 要检查最新流水线的分支或标签。未指定时默认为默认分支。 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/latest"

响应示例

{
    "id": 287,
    "iid": 144,
    "project_id": 21,
    "name": "Build pipeline",
    "sha": "50f0acb76a40e34a4ff304f7347dcc6587da8a14",
    "ref": "main",
    "status": "success",
    "source": "push",
    "created_at": "2022-09-21T01:05:07.200Z",
    "updated_at": "2022-09-21T01:05:50.185Z",
    "web_url": "http://127.0.0.1:3000/test-group/test-project/-/pipelines/287",
    "before_sha": "8a24fb3c5877a6d0b611ca41fc86edc174593e2b",
    "tag": false,
    "yaml_errors": null,
    "user": {
        "id": 1,
        "username": "root",
        "name": "Administrator",
        "state": "active",
        "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
        "web_url": "http://127.0.0.1:3000/root"
    },
    "started_at": "2022-09-21T01:05:14.197Z",
    "finished_at": "2022-09-21T01:05:50.175Z",
    "committed_at": null,
    "duration": 34,
    "queued_duration": 6,
    "coverage": null,
    "detailed_status": {
        "icon": "status_success",
        "text": "passed",
        "label": "passed",
        "group": "success",
        "tooltip": "passed",
        "has_details": false,
        "details_path": "/test-group/test-project/-/pipelines/287",
        "illustration": null,
        "favicon": "/assets/ci_favicons/favicon_status_success-8451333011eee8ce9f2ab25dc487fe24a8758c694827a582f17f42b0a90446a2.png"
    }
}

获取流水线的变量

获取流水线的变量。不包括来自流水线计划的变量。

GET /projects/:id/pipelines/:pipeline_id/variables
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 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"
  }
]

获取流水线的测试报告

{{< alert type=”note” >}}

此 API 路由是 单元测试报告 功能的一部分。

{{< /alert >}}

GET /projects/:id/pipelines/:pipeline_id/test_report
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 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
        }
      ]
    }
  ]
}

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

{{< alert type=”note” >}}

此 API 路由是 单元测试报告 功能的一部分。

{{< /alert >}}

GET /projects/:id/pipelines/:pipeline_id/test_report_summary
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 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
        }
    ]
}

创建新的流水线

{{< history >}}

  • 响应中的 iid 在 极狐GitLab 14.6 引入。
  • inputs 属性在 极狐GitLab 17.10 引入，使用名为 ci_inputs_for_pipelines 的功能标志。默认启用。

{{< /history >}}

POST /projects/:id/pipeline
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
ref string 是 要在其上运行流水线的分支或标签。对于合并请求流水线，请使用 合并请求端点。
variables array 否 包含流水线中可用变量的 哈希数组，结构为 [{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]。如果省略 variable_type，则默认为 env_var。
inputs hash 否 包含输入的 哈希，作为键值对，用于创建流水线。

基本示例：

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

带有 inputs 的请求示例：

curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"inputs": {"environment": "environment", "scan_security": false, "level": 3}}' \
  --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"
}

重试流水线中的作业

{{< history >}}

  • 响应中的 iid 在极狐GitLab 14.6 引入。

{{< /history >}}

重试流水线中失败或取消的作业。如果流水线中没有失败或取消的作业，调用此端点没有效果。

POST /projects/:id/pipelines/:pipeline_id/retry
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 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

{{< alert type=”note” >}}

此端点无论流水线的状态如何，都会返回成功响应 200。

{{< /alert >}}

属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 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"
}

删除流水线

删除流水线将使所有流水线缓存失效，并立即删除所有相关对象，如构建、日志、产物和触发器。此操作无法撤销。

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

DELETE /projects/:id/pipelines/:pipeline_id
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
pipeline_id integer 是 流水线的 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"

更新流水线元数据

您可以更新流水线的元数据。元数据包含流水线的名称。

PUT /projects/:id/pipelines/:pipeline_id/metadata
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径
name string 是 流水线的新名称
pipeline_id integer 是 流水线的 ID

示例请求：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "name=Some new pipeline name" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/metadata"

示例响应：

{
  "id": 46,
  "iid": 11,
  "project_id": 1,
  "status": "running",
  "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",
  "name": "Some new pipeline name"
}