Pipeline schedules

Use this API to interact with pipeline schedules.

List all pipeline schedules

GET /api/v4/projects/{id}/pipeline_schedules

Lists all pipeline schedules for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`scope` Query	String	Scope of pipeline schedules Allowed values: `active`, `inactive` Example: `active`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCiPipelineSchedule
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Create a pipeline schedule

POST /api/v4/projects/{id}/pipeline_schedules

Creates a pipeline schedule.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`

Request body (application/json)

Property	Type	Description
`active`	Boolean	If `true`, activates the pipeline schedule. If `false`, the pipeline schedule is initially deactivated Default: `true` Example: `true`
`cron` Required	String	Cron schedule, for example `0 1 * * ` Example: ` * * * *`
`cron_timezone`	String	Time zone supported by `ActiveSupport::TimeZone`, for example `Pacific Time (US & Canada)`, or `TZInfo::Timezone`, for example `America/Los_Angeles` Default: `UTC` Example: `Asia/Tokyo`
`description` Required	String	Description of the pipeline schedule Example: `Test schedule pipeline`
`inputs`	Array of objects	Array of inputs to pass to the pipeline schedule. Each input has a `name` and a `value`, which can be a string, array, number, or boolean. To delete an existing input, include the `name` field and set `destroy` to `true`
`inputs[].name` Required	String	Name of the input Example: `deploy_strategy`
`inputs[].value` Required	String or array or number or boolean	Value of the input
`ref` Required	String	Branch or tag name that triggers the pipeline. Accepts either short refs (`main`) or full refs (`refs/heads/main` or `refs/tags/main`). Short refs are automatically expanded to full refs, unless the value could match either a branch or a tag Example: `develop`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiPipelineScheduleDetails
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a pipeline schedule

GET /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}

Retrieves a pipeline schedule for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiPipelineScheduleDetails
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Update a pipeline schedule

PUT /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}

Updates a pipeline schedule for a project. After the update is done, it is rescheduled automatically.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`

Request body (application/json)

Property	Type	Description
`active`	Boolean	If `true`, activates the pipeline schedule. If `false`, the pipeline schedule is initially deactivated Example: `true`
`cron`	String	Cron schedule, for example `0 1 * * ` Example: ` * * * *`
`cron_timezone`	String	Time zone supported by `ActiveSupport::TimeZone`, for example `Pacific Time (US & Canada)`, or `TZInfo::Timezone`, for example `America/Los_Angeles` Example: `Asia/Tokyo`
`description`	String	Description of the pipeline schedule Example: `Test schedule pipeline`
`inputs`	Array of objects	Array of inputs to pass to the pipeline schedule. Each input has a `name` and a `value`, which can be a string, array, number, or boolean. To delete an existing input, include the `name` field and set `destroy` to `true`
`inputs[].destroy`	Boolean	If `true`, deletes the input
`inputs[].name` Required	String	Name of the input Example: `deploy_strategy`
`inputs[].value` Required	String or array or number or boolean	Value of the input
`ref`	String	Branch or tag name that triggers the pipeline. Accepts either short refs (`main`) or full refs (`refs/heads/main` or `refs/tags/main`). Short refs are automatically expanded to full refs, unless the value could match either a branch or a tag Example: `develop`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiPipelineScheduleDetails
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Delete a pipeline schedule

DELETE /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}

Deletes a pipeline schedule for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`412`	Precondition Failed	—

List all pipelines triggered by a pipeline schedule

GET /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/pipelines

Lists all pipelines triggered by a pipeline schedule in a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`
`scope` Query	String	Return pipelines in the specified scope Allowed values: `running`, `pending`, `finished`, `branches`, `tags` Example: `pending`
`status` Query	String	Return pipelines with the specified status Allowed values: `created`, `waiting_for_resource`, `preparing`, `waiting_for_callback`, `pending`, `running`, `success`, `failed`, `canceling`, `canceled`, `skipped`, `manual`, `scheduled` Example: `pending`
`updated_before` Query	String (date-time)	Return pipelines updated on or before the specified time Example: `2015-12-24T15:51:21.880Z`
`updated_after` Query	String (date-time)	Return pipelines updated on or after the specified time Example: `2015-12-24T15:51:21.880Z`
`created_before` Query	String (date-time)	Return pipelines created before the specified time Example: `2015-12-24T15:51:21.880Z`
`created_after` Query	String (date-time)	Return pipelines created after the specified time Example: `2015-12-24T15:51:21.880Z`
`sort` Query	String	Sort results in ascending or descending order Allowed values: `asc`, `desc` Default: `asc` Example: `desc`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCiPipelineBasic
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Run a pipeline schedule

POST /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/play

Runs a pipeline schedule immediately. The next scheduled run of this pipeline is not affected.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Create or update ownership of a pipeline schedule

POST /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/take_ownership

Creates or updates the owner of a pipeline schedule for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiPipelineScheduleDetails
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Create a variable for a pipeline schedule

POST /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/variables

Creates a variable for a pipeline schedule.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`

Request body (application/json)

Property	Type	Description
`key` Required	String	Key of the pipeline schedule variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_` Example: `NEW_VARIABLE`
`value` Required	String	Value of the variable Example: `new value`
`variable_type`	String	Type of the variable. Defaults to `env_var` Allowed values: `env_var`, `file`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiVariable
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a variable for a pipeline schedule

GET /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/variables/{key}

Retrieves a specified variable for a pipeline schedule.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`
`key` Path, required	String	Key of the pipeline schedule variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_` Example: `NEW_VARIABLE`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Update a variable for a pipeline schedule

PUT /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/variables/{key}

Updates a variable for a pipeline schedule.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`
`key` Path, required	String	Key of the pipeline schedule variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_` Example: `NEW_VARIABLE`

Request body (application/json)

Property	Type	Description
`value`	String	Value of the variable Example: `new value`
`variable_type`	String	Type of the variable. Defaults to `env_var` Allowed values: `env_var`, `file`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiVariable
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Delete a variable for a pipeline schedule

DELETE /api/v4/projects/{id}/pipeline_schedules/{pipeline_schedule_id}/variables/{key}

Deletes a specified variable for a pipeline schedule.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project Example: `18`
`pipeline_schedule_id` Path, required	Integer	ID of the pipeline schedule Example: `13`
`key` Path, required	String	Key of the pipeline schedule variable. Must be 255 characters or fewer and contain only `A-Z`, `a-z`, `0-9`, and `_` Example: `NEW_VARIABLE`

Responses

Code	Description	Schema
`202`	Accepted	APIEntitiesCiVariable
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiInput

Property	Type	Description
`name`	String	—
`value`	String	—

APIEntitiesCiPipelineBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`status`	String	Example: `success`
`updated_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`

APIEntitiesCiPipelineSchedule

Property	Type	Description
`active`	Boolean	Example: `true`
`created_at`	String (date-time)	Example: `2017-05-19T13:31:08.849Z`
`cron`	String	Example: `* * * * *`
`cron_timezone`	String	Example: `Asia/Tokyo`
`description`	String	Example: `Test schedule pipeline`
`id`	Integer (int64)	Example: `13`
`inputs`	APIEntitiesCiInput	—
`next_run_at`	String (date-time)	Example: `2017-05-19T13:41:00.000Z`
`owner`	APIEntitiesUserBasic	—
`ref`	String	Example: `develop`
`updated_at`	String (date-time)	Example: `2017-05-19T13:40:17.727Z`

APIEntitiesCiPipelineScheduleDetails

Property	Type	Description
`active`	Boolean	Example: `true`
`created_at`	String (date-time)	Example: `2017-05-19T13:31:08.849Z`
`cron`	String	Example: `* * * * *`
`cron_timezone`	String	Example: `Asia/Tokyo`
`description`	String	Example: `Test schedule pipeline`
`id`	Integer (int64)	Example: `13`
`inputs`	APIEntitiesCiInput	—
`last_pipeline`	APIEntitiesCiPipelineBasic	—
`next_run_at`	String (date-time)	Example: `2017-05-19T13:41:00.000Z`
`owner`	APIEntitiesUserBasic	—
`ref`	String	Example: `develop`
`updated_at`	String (date-time)	Example: `2017-05-19T13:40:17.727Z`
`variables`	APIEntitiesCiVariable	—

APIEntitiesCiVariable

Property	Type	Description
`description`	String	Example: `This variable is being used for ...`
`environment_scope`	String	Example: `*`
`hidden`	Boolean	—
`key`	String	Example: `TEST_VARIABLE_1`
`masked`	Boolean	—
`protected`	Boolean	—
`raw`	Boolean	—
`value`	String	Example: `TEST_1`
`variable_type`	String	Example: `env_var`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all pipeline schedules

Create a pipeline schedule

Retrieve a pipeline schedule

Update a pipeline schedule

Delete a pipeline schedule

List all pipelines triggered by a pipeline schedule

Run a pipeline schedule

Create or update ownership of a pipeline schedule

Create a variable for a pipeline schedule

Retrieve a variable for a pipeline schedule

Update a variable for a pipeline schedule

Delete a variable for a pipeline schedule

Schemas

APIEntitiesCiInput

APIEntitiesCiPipelineBasic

APIEntitiesCiPipelineSchedule

APIEntitiesCiPipelineScheduleDetails

APIEntitiesCiVariable

APIEntitiesCustomAttribute

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error