Pipeline schedules API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to interact with 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 or string	Yes	ID or URL-encoded path of the project.
`scope`	string	No	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 or string	Yes	ID or URL-encoded path of the project.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.

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
        }
    ],
    "inputs": [
        {
            "name": "deploy_strategy",
            "value": "blue-green"
        },
        {
            "name": "feature_flags",
            "value": ["flag1", "flag2"]
        }
    ]
}

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 or string	Yes	ID or URL-encoded path of the project.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.

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	Cron schedule, for example: `0 1 * * *`.
`description`	string	Yes	Description of the pipeline schedule.
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`ref`	string	Yes	Branch or tag name that triggers the pipeline. Accepts both short refs (for example: `main`) and full refs (for example: `refs/heads/main` or `refs/tags/main`). Short refs are automatically expanded to full refs, but the request will be rejected if the ref is ambiguous.
`active`	boolean	No	Activates the pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`).
`cron_timezone`	string	No	Time zone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `UTC`).
`inputs`	hash	No	Array of inputs to pass to the pipeline schedule. Each input contains a `name` and `value`. Values can be strings, arrays, numbers, or booleans.

Example request:

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"

Example response:

{
    "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"
    }
}

Example request with inputs:

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" \
     --form "inputs[][name]=deploy_strategy" --form "inputs[][value]=blue-green" \
     "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"

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 or string	Yes	ID or URL-encoded path of the project.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.
`active`	boolean	No	Activates the pipeline schedule. If false is set, the pipeline schedule is initially deactivated.
`cron_timezone`	string	No	Time zone supported by `ActiveSupport::TimeZone` (for example `Pacific Time (US & Canada)`), or `TZInfo::Timezone` (for example `America/Los_Angeles`).
`cron`	string	No	Cron schedule, for example: `0 1 * * *`.
`description`	string	No	Description of the pipeline schedule.
`ref`	string	No	Branch or tag name that triggers the pipeline. Accepts both short refs (for example: `main`) and full refs (for example: `refs/heads/main` or `refs/tags/main`). Short refs are automatically expanded to full refs, but the request will be rejected if the ref is ambiguous.
`inputs`	hash	No	Array of inputs to pass to the pipeline schedule. Each input contains a `name` and `value`. To delete an existing input, include the `name` field and set `destroy` to `true`. Values can be strings, arrays, numbers, or booleans.

Example request:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"

Example response:

{
    "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"
    }
}

Example request with inputs:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form cron="0 2 * * *" \
     --form "inputs[][name]=deploy_strategy" --form "inputs[][value]=rolling" \
     --form "inputs[][name]=existing_input"  --form "inputs[][_destroy]=true" \
     "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"

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 or string	Yes	ID or URL-encoded path of the project.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.

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 or string	Yes	ID or URL-encoded path of the project.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.

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 or string	Yes	ID or URL-encoded path of the project.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.

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 or string	Yes	ID or URL-encoded path of the project.
`key`	string	Yes	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	ID of the pipeline schedule.
`value`	string	Yes	Value of a variable.
`variable_type`	string	No	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 or string	Yes	ID or URL-encoded path of the project.
`key`	string	Yes	Key of a variable.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.
`value`	string	Yes	Value of a variable.
`variable_type`	string	No	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 or string	Yes	ID or URL-encoded path of the project.
`key`	string	Yes	Key of a variable.
`pipeline_schedule_id`	integer	Yes	ID of the pipeline schedule.

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"
}

Troubleshooting

When working with the pipeline schedules API, you might encounter the following issues.

Short refs are expanded to full refs

When you provide a short ref, it is automatically expanded to a full ref. This behavior is intended and ensures explicit resource identification.

The API accepts both short refs (such as main) and full refs (such as refs/heads/main or refs/tags/main).

Ambiguous refs

The API can’t automatically expand a short ref to a full ref when:

Both a branch and a tag exist with the same name as your short ref.
No branch or tag exists with that name.

To resolve this issue, provide the full ref to ensure the correct resource is identified.