파이프라인 스케줄 API
Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
이 API를 사용하여 파이프라인 스케줄과 상호 작용합니다. 프로젝트의 모든 파이프라인 스케줄을 나열합니다. inputs 필드는 Maintainer 또는 Owner 역할을 가진 사용자 또는 스케줄 소유자의 응답에만 포함됩니다.
이 API를 사용하여 파이프라인 스케줄과 상호 작용합니다.
모든 파이프라인 스케줄 목록 조회#
프로젝트의 모든 파이프라인 스케줄을 나열합니다.
GET /projects/:id/pipeline_schedules
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
scope |
string | No | 파이프라인 스케줄 범위. active, inactive 중 하나여야 합니다. |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
[
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "refs/heads/main",
"cron": "* * * * *",
"cron_timezone": "Asia/Tokyo",
"next_run_at": "2017-05-19T13:41:00.000Z",
"active": true,
"created_at": "2017-05-19T13:31:08.849Z",
"updated_at": "2017-05-19T13:40:17.727Z",
"owner": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "https://gitlab.example.com/root"
},
"inputs": [
{
"name": "deploy_strategy",
"value": "blue-green"
},
{
"name": "feature_flags",
"value": ["flag1", "flag2"]
}
]
}
]
Note
inputs 필드는 Maintainer 또는 Owner 역할을 가진 사용자 또는 스케줄 소유자의 응답에만 포함됩니다.
파이프라인 스케줄 조회#
프로젝트의 파이프라인 스케줄을 조회합니다.
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "refs/heads/main",
"cron": "* * * * *",
"cron_timezone": "Asia/Tokyo",
"next_run_at": "2017-05-19T13:41:00.000Z",
"active": true,
"created_at": "2017-05-19T13:31:08.849Z",
"updated_at": "2017-05-19T13:40:17.727Z",
"last_pipeline": {
"id": 332,
"sha": "0e788619d0b5ec17388dffb973ecd505946156db",
"ref": "refs/heads/main",
"status": "pending"
},
"owner": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "https://gitlab.example.com/root"
},
"variables": [
{
"key": "TEST_VARIABLE_1",
"variable_type": "env_var",
"value": "TEST_1",
"raw": false
}
],
"inputs": [
{
"name": "deploy_strategy",
"value": "blue-green"
},
{
"name": "feature_flags",
"value": ["flag1", "flag2"]
}
]
}
Note
inputs 및 variables 필드는 Maintainer 또는 Owner 역할을 가진 사용자 또는 스케줄 소유자의 응답에만 포함됩니다.
파이프라인 스케줄에 의해 트리거된 모든 파이프라인 목록 조회#
프로젝트에서 파이프라인 스케줄에 의해 트리거된 모든 파이프라인을 나열합니다.
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id/pipelines
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
scope |
string | No | 파이프라인 범위. running, pending, finished, branches, tags 중 하나. |
sort |
string | No | 파이프라인을 asc 또는 desc 순서로 정렬합니다. 기본값은 asc. |
status |
string | No | 파이프라인 상태. created, waiting_for_resource, preparing, pending, running, success, failed, canceled, skipped, manual, scheduled 중 하나. |
updated_after |
datetime | No | 지정된 날짜 이후에 업데이트된 파이프라인을 반환합니다. ISO 8601 형식으로 예상됩니다 (2019-03-15T08:00:00Z). |
updated_before |
datetime | No | 지정된 날짜 이전에 업데이트된 파이프라인을 반환합니다. ISO 8601 형식으로 예상됩니다 (2019-03-15T08:00:00Z). |
created_after |
datetime | No | 지정된 날짜 이후에 생성된 파이프라인을 반환합니다. ISO 8601 형식으로 예상됩니다 (2019-03-15T08:00:00Z). |
created_before |
datetime | No | 지정된 날짜 이전에 생성된 파이프라인을 반환합니다. ISO 8601 형식으로 예상됩니다 (2019-03-15T08:00:00Z). |
요청 예시:
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/pipelines"
응답 예시:
[
{
"id": 47,
"iid": 12,
"project_id": 29,
"status": "pending",
"source": "scheduled",
"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": 29,
"status": "pending",
"source": "scheduled",
"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"
}
]
새 파이프라인 스케줄 생성#
히스토리
inputs속성이 GitLab 17.11에서ci_inputs_for_pipelines라는 플래그와 함께 도입됨. 기본적으로 활성화됨.inputs속성이 GitLab 18.1에서 일반적으로 사용 가능. 기능 플래그ci_inputs_for_pipelines제거됨.
프로젝트의 새 파이프라인 스케줄을 생성합니다.
POST /projects/:id/pipeline_schedules
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
cron |
string | Yes | Cron 스케줄, 예: 0 1 * * *. |
description |
string | Yes | 파이프라인 스케줄 설명. |
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
ref |
string | Yes | 파이프라인을 트리거하는 브랜치 또는 태그 이름. 짧은 ref(main) 또는 전체 ref(refs/heads/main 또는 refs/tags/main)를 모두 허용합니다. 짧은 ref는 브랜치와 태그 모두와 일치할 수 있는 값이 아닌 한 자동으로 전체 ref로 확장됩니다. |
active |
boolean | No | 파이프라인 스케줄을 활성화합니다. false로 설정하면 파이프라인 스케줄이 초기에 비활성화됩니다 (기본값: true). |
cron_timezone |
string | No | ActiveSupport::TimeZone에서 지원하는 시간대, 예: Pacific Time (US & Canada) (기본값: UTC). |
inputs |
hash | No | 파이프라인 스케줄에 전달할 인풋 배열. 각 인풋에는 name과 value가 포함됩니다. 값은 문자열, 배열, 숫자 또는 불리언이 될 수 있습니다. |
요청 예시:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" \
--form "description=Build packages" \
--form "ref=main" \
--form "cron=0 1 * * 5" \
--form "cron_timezone=UTC" \
--form "active=true"
응답 예시:
{
"id": 14,
"description": "Build packages",
"ref": "refs/heads/main",
"cron": "0 1 * * 5",
"cron_timezone": "UTC",
"next_run_at": "2017-05-26T01:00:00.000Z",
"active": true,
"created_at": "2017-05-19T13:43:08.169Z",
"updated_at": "2017-05-19T13:43:08.169Z",
"last_pipeline": null,
"owner": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "https://gitlab.example.com/root"
}
}
inputs를 사용하는 요청 예시:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" \
--form "description=Build packages" \
--form "ref=main" \
--form "cron=0 1 * * 5" \
--form "cron_timezone=UTC" \
--form "active=true" \
--form "inputs[][name]=deploy_strategy" \
--form "inputs[][value]=blue-green"
파이프라인 스케줄 업데이트#
프로젝트의 파이프라인 스케줄을 업데이트합니다. 업데이트가 완료되면 자동으로 재스케줄됩니다.
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
active |
boolean | No | 파이프라인 스케줄을 활성화합니다. false로 설정하면 파이프라인 스케줄이 초기에 비활성화됩니다. |
cron_timezone |
string | No | ActiveSupport::TimeZone에서 지원하는 시간대 (예: Pacific Time (US & Canada)), 또는 TZInfo::Timezone (예: America/Los_Angeles). |
cron |
string | No | Cron 스케줄, 예: 0 1 * * *. |
description |
string | No | 파이프라인 스케줄 설명. |
ref |
string | No | 파이프라인을 트리거하는 브랜치 또는 태그 이름. 짧은 ref(main) 또는 전체 ref(refs/heads/main 또는 refs/tags/main)를 모두 허용합니다. 짧은 ref는 브랜치와 태그 모두와 일치할 수 있는 값이 아닌 한 자동으로 전체 ref로 확장됩니다. |
inputs |
hash | No | 파이프라인 스케줄에 전달할 인풋 배열. 각 인풋에는 name과 value가 포함됩니다. 기존 인풋을 삭제하려면 name 필드를 포함하고 destroy를 true로 설정합니다. 값은 문자열, 배열, 숫자 또는 불리언이 될 수 있습니다. |
요청 예시:
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" \
--form "cron=0 2 * * *"
응답 예시:
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "refs/heads/main",
"cron": "0 2 * * *",
"cron_timezone": "Asia/Tokyo",
"next_run_at": "2017-05-19T17:00:00.000Z",
"active": true,
"created_at": "2017-05-19T13:31:08.849Z",
"updated_at": "2017-05-19T13:44:16.135Z",
"last_pipeline": {
"id": 332,
"sha": "0e788619d0b5ec17388dffb973ecd505946156db",
"ref": "refs/heads/main",
"status": "pending"
},
"owner": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "https://gitlab.example.com/root"
}
}
inputs를 사용하는 요청 예시:
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" \
--form "cron=0 2 * * *" \
--form "inputs[][name]=deploy_strategy" \
--form "inputs[][value]=rolling" \
--form "inputs[][name]=existing_input" \
--form "inputs[][destroy]=true"
파이프라인 스케줄 소유권 업데이트#
프로젝트 파이프라인 스케줄의 소유자를 업데이트합니다.
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/take_ownership"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "refs/heads/main",
"cron": "0 2 * * *",
"cron_timezone": "Asia/Tokyo",
"next_run_at": "2017-05-19T17:00:00.000Z",
"active": true,
"created_at": "2017-05-19T13:31:08.849Z",
"updated_at": "2017-05-19T13:46:37.468Z",
"last_pipeline": {
"id": 332,
"sha": "0e788619d0b5ec17388dffb973ecd505946156db",
"ref": "refs/heads/main",
"status": "pending"
},
"owner": {
"name": "shinya",
"username": "maeda",
"id": 50,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
"web_url": "https://gitlab.example.com/maeda"
}
}
파이프라인 스케줄 삭제#
프로젝트의 파이프라인 스케줄을 삭제합니다.
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "refs/heads/main",
"cron": "0 2 * * *",
"cron_timezone": "Asia/Tokyo",
"next_run_at": "2017-05-19T17:00:00.000Z",
"active": true,
"created_at": "2017-05-19T13:31:08.849Z",
"updated_at": "2017-05-19T13:46:37.468Z",
"last_pipeline": {
"id": 332,
"sha": "0e788619d0b5ec17388dffb973ecd505946156db",
"ref": "refs/heads/main",
"status": "pending"
},
"owner": {
"name": "shinya",
"username": "maeda",
"id": 50,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
"web_url": "https://gitlab.example.com/maeda"
}
}
파이프라인 스케줄 즉시 실행#
파이프라인 스케줄을 즉시 실행합니다. 이 파이프라인의 다음 예약된 실행에는 영향을 미치지 않습니다.
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
요청 예시:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/42/pipeline_schedules/1/play"
응답 예시:
{
"message": "201 Created"
}
파이프라인 스케줄에 대한 변수 생성#
파이프라인 스케줄에 새 변수를 생성합니다.
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
key |
string | Yes | 변수의 키. 최대 255자. A-Z, a-z, 0-9, _만 허용됩니다. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
value |
string | Yes | 변수의 값. |
variable_type |
string | No | 변수 유형. 사용 가능한 유형은 env_var (기본값) 및 file입니다. |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables" \
--form "key=NEW_VARIABLE" \
--form "value=new value"
{
"key": "NEW_VARIABLE",
"variable_type": "env_var",
"value": "new value"
}
파이프라인 스케줄에 대한 변수 조회#
히스토리
- GitLab 18.7에서 도입됨.
파이프라인 스케줄에 대한 변수를 조회합니다.
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
key |
string | Yes | 변수의 키. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
성공하면 200 OK와 다음 응답 속성을 반환합니다:
| 속성 | 유형 | 설명 |
|---|---|---|
key |
string | 변수의 키. |
value |
string | 변수의 값. |
variable_type |
string | 변수 유형. env_var 또는 file. |
요청 예시:
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
응답 예시:
{
"key": "NEW_VARIABLE",
"variable_type": "env_var",
"value": "new value"
}
파이프라인 스케줄에 대한 변수 업데이트#
파이프라인 스케줄에 대한 변수를 업데이트합니다.
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
key |
string | Yes | 변수의 키. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
value |
string | Yes | 변수의 값. |
variable_type |
string | No | 변수 유형. 사용 가능한 유형은 env_var (기본값) 및 file입니다. |
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" \
--form "value=updated value"
{
"key": "NEW_VARIABLE",
"value": "updated value",
"variable_type": "env_var"
}
파이프라인 스케줄에 대한 변수 삭제#
파이프라인 스케줄에 대한 변수를 삭제합니다.
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | Yes | 프로젝트의 ID 또는 URL 인코딩된 경로. |
key |
string | Yes | 변수의 키. |
pipeline_schedule_id |
integer | Yes | 파이프라인 스케줄의 ID. |
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
{
"key": "NEW_VARIABLE",
"value": "updated value"
}
모호한 ref#
다음과 같은 경우 API가 짧은 ref를 전체 ref로 자동 확장할 수 없습니다:
- 짧은
ref와 동일한 이름의 브랜치와 태그가 모두 존재하는 경우. - 해당 이름의 브랜치 또는 태그가 존재하지 않는 경우.
이 문제를 해결하려면 올바른 리소스가 식별되도록 전체 ref를 제공하십시오.