Pipeline schedules API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
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": "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"
}
}
]
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": "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
}
]
}
Get all pipelines triggered by a pipeline schedule
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 |
---|---|---|---|
cron | string | Yes | The cron schedule, for example: 0 1 * * * . |
description | string | Yes | The description of the pipeline schedule. |
id | integer/string | Yes | The ID or URL-encoded path of the project. |
ref | string | Yes | The branch or tag name that is triggered. Both the short (e.g. main ) and full (e.g. refs/heads/main or refs/tags/main ) ref versions are accepted. If a short version is provided, it is automatically expanded to the full ref version but, if the ref is ambiguous, it will be rejected |
active | boolean | No | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: true ). |
cron_timezone | string | No | The time zone supported by ActiveSupport::TimeZone , for example: Pacific Time (US & Canada) (default: UTC ). |
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": "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"
}
}
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. |
active | boolean | No | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. |
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 ). |
cron | string | No | The cron schedule, for example: 0 1 * * * . |
description | string | No | The description of the pipeline schedule. |
ref | string | No | The branch or tag name that is triggered. Both the short (e.g. main ) and full (e.g. refs/heads/main or refs/tags/main ) ref versions are accepted. If a short version is provided, it is automatically expanded to the full ref version but, if the ref is ambiguous, it will be rejected |
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": "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"
}
}
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": "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 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": "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"
}
}
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 |
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 |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
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 |
key | string | Yes | The key of a variable |
pipeline_schedule_id | integer | Yes | The pipeline schedule ID |
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 |
key | string | Yes | The key of a variable |
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/variables/NEW_VARIABLE"
{
"key": "NEW_VARIABLE",
"value": "updated value"
}
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support