- Get all pipeline schedules
- Get a single pipeline schedule
- Get all pipelines triggered by a pipeline schedule
- Create a new pipeline schedule
- Edit a pipeline schedule
- Take ownership of a pipeline schedule
- Delete a pipeline schedule
- Run a scheduled pipeline immediately
- Pipeline schedule variables
- Create a new pipeline schedule variable
- Edit a pipeline schedule variable
- Delete a pipeline schedule variable
Pipeline schedules API
You can read more about pipeline schedules.
Get all pipeline schedules
Get a list of the pipeline schedules of a project.
GET /projects/:id/pipeline_schedules
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
scope | string | No | The scope of pipeline schedules, must be one of: active, inactive
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
[
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "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"
}
}
]
Get a single pipeline schedule
Get the pipeline schedule of a project.
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "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": "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"
}
]
}
Get all pipelines triggered by a pipeline schedule
Introduced in GitLab 15.3.
Get all pipelines triggered by a pipeline schedule in a project.
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id/pipelines
Supported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project. |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/pipelines"
Example response:
[
{
"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"
}
]
Create a new pipeline schedule
Create a new pipeline schedule of a project.
POST /projects/:id/pipeline_schedules
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project. |
description | string | Yes | The description of the pipeline schedule. |
ref | string | Yes | The branch or tag name that is triggered. |
cron | string | Yes | The cron schedule, for example: 0 1 * * *. |
cron_timezone | string | No | The time zone supported by ActiveSupport::TimeZone, for example: Pacific Time (US & Canada) (default: UTC). |
active | boolean | No | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: true). |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--form description="Build packages" --form ref="main" --form cron="0 1 * * 5" --form cron_timezone="UTC" \
--form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
{
"id": 14,
"description": "Build packages",
"ref": "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"
}
}
Edit a pipeline schedule
Updates the pipeline schedule of a project. After the update is done, it is rescheduled automatically.
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project. |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID. |
description | string | No | The description of the pipeline schedule. |
ref | string | No | The branch or tag name that is triggered. |
cron | string | No | The cron schedule, for example: 0 1 * * *. |
cron_timezone | string | No | The time zone supported by ActiveSupport::TimeZone (for example Pacific Time (US & Canada)), or TZInfo::Timezone (for example America/Los_Angeles). |
active | boolean | No | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "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": "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"
}
}
Take ownership of a pipeline schedule
Update the owner of the pipeline schedule of a project.
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/take_ownership"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "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": "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 a pipeline schedule
Delete the pipeline schedule of a project.
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
"id": 13,
"description": "Test schedule pipeline",
"ref": "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": "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"
}
}
Run a scheduled pipeline immediately
Trigger a new scheduled pipeline, which runs immediately. The next scheduled run of this pipeline is not affected.
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/pipeline_schedules/1/play"
Example response:
{
"message": "201 Created"
}
Pipeline schedule variables
Create a new pipeline schedule variable
Create a new variable of a pipeline schedule.
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
key | string | Yes | The key of a variable; must have no more than 255 characters; only A-Z, a-z, 0-9, and _ are allowed |
value | string | Yes | The value of a variable |
variable_type | string | No | The type of a variable. Available types are: env_var (default) and file
|
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "key=NEW_VARIABLE" \
--form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables"
{
"key": "NEW_VARIABLE",
"variable_type": "env_var",
"value": "new value"
}
Edit a pipeline schedule variable
Updates the variable of a pipeline schedule.
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
key | string | Yes | The key of a variable |
value | string | Yes | The value of a variable |
variable_type | string | No | The type of a variable. Available types are: env_var (default) and file
|
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "value=updated value" \
"https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
{
"key": "NEW_VARIABLE",
"value": "updated value",
"variable_type": "env_var"
}
Delete a pipeline schedule variable
Delete the variable of a pipeline schedule.
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | Yes | The ID or URL-encoded path of the project |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
key | string | Yes | The key of a variable |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
{
"key": "NEW_VARIABLE",
"value": "updated value"
}