パイプラインAPI

パイプラインのページネーション

デフォルトでは、APIの結果はページ分割されているため、GET リクエストは一度に20件の結果を返します。

ページ分割についての詳細はこちらをご覧ください。

プロジェクトパイプライン一覧

  • iid GitLab 14.6 で導入されたレスポンスで、単一のパイプラインを取得します。
  • name in responseはGitLab 15.11でpipeline_name_in_api というフラグとともに 導入されました。デフォルトでは無効です。
  • name in request 15.11で導入された pipeline_name_search というフラグ。デフォルトでは無効です。
  • name in responseはGitLab 16.3で一般的に利用可能になりました。機能フラグpipeline_name_in_api は削除されました。

フラグ: セルフマネジメントの GitLab では、デフォルトでリクエストのname フィールドは無視されます。これを利用可能にするには、管理者がpipeline_name_search という機能フラグを有効にします。GitLab.comでは、この機能は利用可能です。

プロジェクト内のパイプラインを一覧表示します。子パイプラインは結果に含まれませんが、子パイプラインを個別に取得できます。

GET /projects/:id/pipelines
属性種類必須説明
id整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
scope文字列です。なしパイプラインの範囲：running pending,finished,branches 、tags
status文字列です。なしパイプラインの状況、1つ：created waiting_for_resource,preparing,pending,running,success,failed,canceled,skipped,manual、scheduled
source文字列です。なし GitLab 14.3以降では、パイプラインがどのようにトリガーされたか、次のいずれかです：pushweb,trigger,schedule,api,external,pipeline,chat,webide,merge_request_event,external_pull_request_event,parent_pipeline,ondemand_dast_scan, またはondemand_dast_validation。
ref文字列です。なしパイプラインのレフ
sha文字列です。なしパイプラインのSHA
yaml_errorsbooleanなし無効な設定のパイプラインを返します。
username文字列です。なしパイプラインをトリガーしたユーザーのユーザー名
updated_afterdatetimeなし指定された日付以降に更新されたパイプラインを返します。ISO 8601 形式 (2019-03-15T08:00:00Z) で返されます。
updated_beforedatetimeなし指定された日付以前に更新されたパイプラインを返します。ISO 8601 形式 (2019-03-15T08:00:00Z) で返されます。
name文字列です。なし指定した名前のパイプラインを返します。GitLab 15.11で導入されましたが、デフォルトでは利用できません。
order_by文字列です。なし id,status,ref,updated_at またはuser_id (デフォルト:id) でパイプラインをオーダー。
sort文字列です。なしパイプラインをasc またはdesc 順番に desc並べ替えます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",
    "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"
  }
]

パイプラインの取得

  • iid GitLab 14.6 で導入されたレスポンスで、単一のパイプラインを取得します。
  • name in responseはGitLab 15.11でpipeline_name_in_api というフラグとともに 導入されました。デフォルトでは無効です。
  • name in responseはGitLab 16.3で一般的に利用可能になりました。機能フラグpipeline_name_in_api は削除されました。

プロジェクトから1つのパイプラインを取得します。

子パイプラインを 1 つ取得することもできます。

GET /projects/:id/pipelines/:pipeline_id
属性種類必須説明
id整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインの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,
  "name": "Build pipeline",
  "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整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインの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"
  }
]

パイプラインのテストレポートの取得

note
この API 経路は、ユニットテストレポート機能の一部です。
GET /projects/:id/pipelines/:pipeline_id/test_report
属性種類必須説明
id整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインの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
        }
      ]
    }
  ]
}

パイプラインのテストレポート概要の取得

GitLab 14.2で導入されました。

note
この API 経路は、ユニットテストレポート機能の一部です。
GET /projects/:id/pipelines/:pipeline_id/test_report_summary
属性種類必須説明
id整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインの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
        }
    ]
}

最新のパイプラインの取得

  • name in responseはGitLab 15.11でpipeline_name_in_api というフラグとともに 導入されました。デフォルトでは無効です。
  • name in responseはGitLab 16.3で一般的に利用可能になりました。機能フラグpipeline_name_in_api は削除されました。

プロジェクト内の特定の参照に対する最新のパイプラインを取得します。

GET /projects/:id/pipelines/latest
属性種類必須説明
ref文字列です。なし最新のパイプラインをチェックするブランチまたはタグ。指定しない場合のデフォルトはデフォルトブランチです。
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"
    }
}

新しいパイプラインの作成

iid GitLab 14.6 で導入されたレスポンスで、単一のパイプラインを取得します。

POST /projects/:id/pipeline
属性種類必須説明
id整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
ref文字列です。はいパイプラインを実行するブランチまたはタグ。
variablesアレイなしパイプラインで利用可能な変数を含むハッシュの配列で、[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]構造体にマッチします。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 GitLab 14.6 で導入されたレスポンスで、単一のパイプラインを取得します。

POST /projects/:id/pipelines/:pipeline_id/retry
属性種類必須説明
id整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインの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整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインの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整数/文字列はい プロジェクトのIDまたはURLエンコードされたパス
pipeline_id整数。はいパイプラインのID
curl --header "PRIVATE-TOKEN: <your_access_token>" --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46"