Pipeline schedules API
DETAILS: 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
- Introduced in GitLab 15.3.
Get all pipelines triggered by a pipeline schedule in a project.
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id/pipelinesSupported 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 --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```0
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```1
## Edit a pipeline schedule
Updates the pipeline schedule of a project. After the update is done, it is rescheduled automatically.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```2
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `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](https://en.wikipedia.org/wiki/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](../ci/pipelines/schedules.md#ambiguous-refs), it will be rejected |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```3
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```4
## Take ownership of a pipeline schedule
Update the owner of the pipeline schedule of a project.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```5
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `pipeline_schedule_id` | integer | Yes | The pipeline schedule ID |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```6
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```7
## Delete a pipeline schedule
Delete the pipeline schedule of a project.
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```8
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `pipeline_schedule_id` | integer | Yes | The pipeline schedule ID |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
```9
```json
[
{
"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"
}
}
]
```0
## Run a scheduled pipeline immediately
Trigger a new scheduled pipeline, which runs immediately. The next scheduled run
of this pipeline is not affected.
```json
[
{
"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"
}
}
]
```1
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `pipeline_schedule_id` | integer | Yes | The pipeline schedule ID |
Example request:
```json
[
{
"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"
}
}
]
```2
Example response:
```json
[
{
"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"
}
}
]
```3
## Pipeline schedule variables
## Create a new pipeline schedule variable
Create a new variable of a pipeline schedule.
```json
[
{
"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"
}
}
]
```4
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `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` |
```json
[
{
"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"
}
}
]
```5
```json
[
{
"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"
}
}
]
```6
## Edit a pipeline schedule variable
Updates the variable of a pipeline schedule.
```json
[
{
"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"
}
}
]
```7
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `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` |
```json
[
{
"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"
}
}
]
```8
```json
[
{
"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"
}
}
]
```9
## Delete a pipeline schedule variable
Delete the variable of a pipeline schedule.
```plaintext
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
```0
| Attribute | Type | Required | Description |
|------------------------|----------------|----------|-------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `key` | string | Yes | The `key` of a variable |
| `pipeline_schedule_id` | integer | Yes | The pipeline schedule ID |
```plaintext
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
```1
```plaintext
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
```2