이 API를 사용하여 CI/CD 파이프라인을 다룹니다.

파이프라인 목록 조회#

히스토리

• GitLab 19.3에서 도입되었습니다.
• project 필드가 GitLab 19.4에서 도입되었습니다.
• detailed_status, started_at, finished_at, duration, queued_duration, merge_request 필드가 GitLab 19.4에서 도입되었습니다.

인증된 사용자가 트리거한 모든 프로젝트의 파이프라인을 조회합니다.

최근에 생성된 파이프라인만 반환됩니다. 특정 프로젝트의 전체 파이프라인 이력을 조회하려면 프로젝트 파이프라인 목록 조회를 사용합니다.

사용자가 더 이상 액세스할 수 없는 프로젝트의 파이프라인은 결과에 포함되지 않습니다. 기본적으로 하위 파이프라인은 결과에 포함되지 않습니다. 하위 파이프라인을 반환하려면 source를 parent_pipeline로 설정합니다.

merge_request 필드는 머지 리퀘스트가 사용자에게 표시되는 머지 리퀘스트 파이프라인에만 포함됩니다.

GET /pipelines

결과는 페이지네이션되며 페이지당 최대 100건을 반환합니다(기본값 20건). 오프셋 기반 페이지네이션은 지원되지 않습니다. 다음 결과 페이지를 조회하려면 Link 응답 헤더의 URL을 사용합니다.

지원되는 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/pipelines?created_after=2016-08-11T00:00:00Z"

응답 예시

[
  {
    "id": 47,
    "iid": 12,
    "project_id": 1,
    "status": "running",
    "source": "merge_request_event",
    "ref": "refs/merge-requests/14/merge",
    "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",
    "started_at": "2016-08-11T11:28:54.085Z",
    "finished_at": null,
    "duration": null,
    "queued_duration": 20,
    "detailed_status": {
      "icon": "status_running",
      "text": "Running",
      "label": "running",
      "group": "running",
      "tooltip": "running",
      "has_details": true,
      "details_path": "/foo/bar/-/pipelines/47",
      "illustration": null,
      "favicon": "/assets/ci_favicons/favicon_status_running.png"
    },
    "merge_request": {
      "iid": 14,
      "title": "Add rate limiting to the public API",
      "web_url": "https://example.com/foo/bar/-/merge_requests/14"
    },
    "project": {
      "id": 1,
      "description": "",
      "name": "Bar",
      "name_with_namespace": "Foo / Bar",
      "path": "bar",
      "path_with_namespace": "foo/bar",
      "created_at": "2016-08-10T09:00:00.000Z"
    }
  },
  {
    "id": 51,
    "iid": 5,
    "project_id": 3,
    "status": "success",
    "source": "web",
    "ref": "main",
    "sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a",
    "name": "Deploy pipeline",
    "web_url": "https://example.com/foo/baz/pipelines/51",
    "created_at": "2016-08-11T09:07:01.514Z",
    "updated_at": "2016-08-11T09:12:44.782Z",
    "started_at": "2016-08-11T09:07:31.514Z",
    "finished_at": "2016-08-11T09:12:44.782Z",
    "duration": 313,
    "queued_duration": 30,
    "detailed_status": {
      "icon": "status_success",
      "text": "Passed",
      "label": "passed",
      "group": "success",
      "tooltip": "passed",
      "has_details": true,
      "details_path": "/foo/baz/-/pipelines/51",
      "illustration": null,
      "favicon": "/assets/ci_favicons/favicon_status_success.png"
    },
    "project": {
      "id": 3,
      "description": "",
      "name": "Baz",
      "name_with_namespace": "Foo / Baz",
      "path": "baz",
      "path_with_namespace": "foo/baz",
      "created_at": "2016-08-10T09:00:00.000Z"
    }
  }
]

프로젝트 파이프라인 목록 조회#

히스토리

• source를 parent_pipeline로 설정해 하위 파이프라인을 반환하는 기능이 GitLab 17.0에서 도입되었습니다.

프로젝트의 파이프라인을 조회합니다.

기본적으로 하위 파이프라인은 결과에 포함되지 않습니다. 하위 파이프라인을 반환하려면 source를 parent_pipeline로 설정합니다.

GET /projects/:id/pipelines

결과의 페이지네이션은 page와 per_page 페이지네이션 파라미터로 제어합니다.

scope를 branches 또는 tags로 설정하면 API는 각 브랜치 또는 태그 ref의 최신 파이프라인만 반환합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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"
  }
]

단일 파이프라인 조회#

프로젝트에서 단일 파이프라인을 조회합니다.

단일 하위 파이프라인도 조회할 수 있습니다.

GET /projects/:id/pipelines/:pipeline_id

결과의 페이지네이션은 page와 per_page 페이지네이션 파라미터로 제어합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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"
  },
  "archived": false
}

최신 파이프라인 조회#

프로젝트의 특정 ref에서 가장 최근 커밋의 최신 파이프라인을 조회합니다. 해당 커밋에 파이프라인이 없으면 403 상태 코드를 반환합니다.

GET /projects/:id/pipelines/latest

결과의 페이지네이션은 page와 per_page 페이지네이션 파라미터로 제어합니다.

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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"
    },
    "archived": false
}

파이프라인 변수 조회#

파이프라인의 파이프라인 변수를 조회합니다.

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

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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 /projects/:id/pipelines/:pipeline_id/test_report

결과의 페이지네이션은 page와 per_page 페이지네이션 파라미터로 제어합니다.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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
        }
      ]
    }
  ]
}

파이프라인의 테스트 리포트 요약 조회#

GET /projects/:id/pipelines/:pipeline_id/test_report_summary

결과의 페이지네이션은 page와 per_page 페이지네이션 파라미터로 제어합니다.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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
        }
    ]
}

새 파이프라인 생성#

히스토리

• inputs 속성이 GitLab 17.10에서 ci_inputs_for_pipelines라는 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화되어 있습니다.
• inputs 속성이 GitLab 18.1에서 일반 공급되었습니다. 기능 플래그 ci_inputs_for_pipelines는 제거되었습니다.

POST /projects/:id/pipeline

기본 예시:

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

입력값을 사용하는 요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main" \
  --data '{"inputs": {"environment": "environment", "scan_security": false, "level": 3}}'

응답 예시

{
  "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",
  "archived": false
}

파이프라인의 job 재시도#

히스토리

• 같은 파이프라인의 동시 재시도에 대한 409 Conflict 응답이 GitLab 19.5에서 lock_concurrent_pipeline_retries라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.

파이프라인에서 실패하거나 취소된 job을 재시도합니다. 파이프라인에 실패하거나 취소된 job 이 없으면 이 엔드포인트를 호출해도 아무 변화가 없습니다.

파이프라인 재시도 속도 제한을 초과하면 이 엔드포인트는 429 Too Many Requests 상태 코드를 반환합니다.

특정 파이프라인의 재시도는 한 번에 하나만 실행됩니다. 같은 파이프라인의 재시도가 이미 진행 중이면 이 엔드포인트는 409 Conflict 상태 코드를 반환합니다. 재시도가 끝날 때까지 기다린 다음 요청을 다시 보냅니다.

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

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
  "archived": false
}

파이프라인의 모든 job 취소#

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

파이프라인 취소 속도 제한을 초과하면 이 엔드포인트는 Retry-After 헤더와 함께 429 Too Many Requests 상태 코드를 반환합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
  "archived": false
}

파이프라인 삭제#

파이프라인을 삭제하면 모든 파이프라인 캐시가 만료되고, 빌드·로그·아티팩트·트리거처럼 직접 관련된 객체가 모두 삭제됩니다. 이 작업은 되돌릴 수 없습니다.

이 엔드포인트에는 속도 제한이 적용되며, 제한을 초과하면 Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다.

파이프라인을 삭제해도 하위 파이프라인이 자동으로 삭제되지는 않습니다. 자세한 내용은 관련 이슈를 참고합니다.

사전 요구 사항:

• 프로젝트에 대한 Owner 권한이 필요합니다.

DELETE /projects/:id/pipelines/:pipeline_id

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

파이프라인 메타데이터 업데이트#

파이프라인 메타데이터를 업데이트합니다. 메타데이터에는 파이프라인의 이름이 포함됩니다.

PUT /projects/:id/pipelines/:pipeline_id/metadata

요청 예시:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/1/pipelines/46/metadata" \
  --data '{"name": "Some new pipeline name"}'

응답 예시:

{
  "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",
  "archived": false
}