debian-mirror-gitlab/doc/api/pipeline_schedules.md

460 lines
17 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Verify
2021-09-04 01:27:46 +05:30
group: Pipeline Execution
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-10-24 23:57:45 +05:30
---
2021-09-04 01:27:46 +05:30
# Pipeline schedules API **(FREE)**
2017-09-10 17:25:29 +05:30
2020-04-08 14:13:33 +05:30
You can read more about [pipeline schedules](../ci/pipelines/schedules.md).
2017-09-10 17:25:29 +05:30
## Get all pipeline schedules
Get a list of the pipeline schedules of a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
GET /projects/:id/pipeline_schedules
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2017-09-10 17:25:29 +05:30
| `scope` | string | no | The scope of pipeline schedules, one of: `active`, `inactive` |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
2017-09-10 17:25:29 +05:30
```
```json
[
{
"id": 13,
"description": "Test schedule pipeline",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
```
| Attribute | Type | required | Description |
|--------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2017-09-10 17:25:29 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
2017-09-10 17:25:29 +05:30
```
```json
{
"id": 13,
"description": "Test schedule pipeline",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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"
2018-03-17 18:26:18 +05:30
},
"variables": [
{
"key": "TEST_VARIABLE_1",
2019-07-31 22:56:46 +05:30
"variable_type": "env_var",
2018-03-17 18:26:18 +05:30
"value": "TEST_1"
}
]
2017-09-10 17:25:29 +05:30
}
```
2022-08-27 11:52:29 +05:30
## Get all pipelines triggered by a pipeline schedule
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368566) in GitLab 15.3.
Get all pipelines triggered by a pipeline schedule in a project.
```plaintext
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](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/pipelines"
```
Example response:
```json
[
{
"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"
}
]
```
2017-09-10 17:25:29 +05:30
## Create a new pipeline schedule
Create a new pipeline schedule of a project.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
POST /projects/:id/pipeline_schedules
```
2021-02-22 17:27:13 +05:30
| Attribute | Type | required | Description |
|-----------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-02-22 17:27:13 +05:30
| `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](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. |
2021-11-18 22:05:49 +05:30
| `cron_timezone` | string | no | The time zone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `UTC`). |
2021-02-22 17:27:13 +05:30
| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`). |
2017-09-10 17:25:29 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
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"
2017-09-10 17:25:29 +05:30
```
```json
{
"id": 14,
"description": "Build packages",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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
2021-02-22 17:27:13 +05:30
Updates the pipeline schedule of a project. Once the update is done, it is rescheduled automatically.
2017-09-10 17:25:29 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id
```
2021-02-22 17:27:13 +05:30
| Attribute | Type | required | Description |
|------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-02-22 17:27:13 +05:30
| `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](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. |
2021-11-18 22:05:49 +05:30
| `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`). |
2021-02-22 17:27:13 +05:30
| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. |
2017-09-10 17:25:29 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
2017-09-10 17:25:29 +05:30
```
```json
{
"id": 13,
"description": "Test schedule pipeline",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership
```
| Attribute | Type | required | Description |
|---------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2017-09-10 17:25:29 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/take_ownership"
2017-09-10 17:25:29 +05:30
```
```json
{
"id": 13,
"description": "Test schedule pipeline",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id
```
| Attribute | Type | required | Description |
|----------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2017-09-10 17:25:29 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
2017-09-10 17:25:29 +05:30
```
```json
{
"id": 13,
"description": "Test schedule pipeline",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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",
2021-09-04 01:27:46 +05:30
"ref": "main",
2017-09-10 17:25:29 +05:30
"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"
}
}
```
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
## Run a scheduled pipeline immediately
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201786) in GitLab 12.8.
2020-03-13 15:44:24 +05:30
Trigger a new scheduled pipeline, which runs immediately. The next scheduled run
of this pipeline is not affected.
2020-05-24 23:13:21 +05:30
```plaintext
2020-03-13 15:44:24 +05:30
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play
```
| Attribute | Type | required | Description |
| ---------------- | --------- | ---------- | -------------------------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2020-03-13 15:44:24 +05:30
Example request:
2020-05-24 23:13:21 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/pipeline_schedules/1/play"
2020-03-13 15:44:24 +05:30
```
Example response:
```json
{
"message": "201 Created"
}
```
2019-07-07 11:18:12 +05:30
## Pipeline schedule variables
2018-03-17 18:26:18 +05:30
## Create a new pipeline schedule variable
Create a new variable of a pipeline schedule.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables
```
| Attribute | Type | required | Description |
|------------------------|----------------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2018-03-17 18:26:18 +05:30
| `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 |
2019-07-31 22:56:46 +05:30
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
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"
2018-03-17 18:26:18 +05:30
```
```json
{
"key": "NEW_VARIABLE",
2019-07-31 22:56:46 +05:30
"variable_type": "env_var",
2018-03-17 18:26:18 +05:30
"value": "new value"
}
```
## Edit a pipeline schedule variable
Updates the variable of a pipeline schedule.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
```
| Attribute | Type | required | Description |
|------------------------|----------------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2018-03-17 18:26:18 +05:30
| `key` | string | yes | The `key` of a variable |
| `value` | string | yes | The `value` of a variable |
2019-07-31 22:56:46 +05:30
| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` |
2018-03-17 18:26:18 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
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"
2018-03-17 18:26:18 +05:30
```
```json
{
"key": "NEW_VARIABLE",
2021-06-08 01:23:25 +05:30
"value": "updated value",
"variable_type": "env_var"
2018-03-17 18:26:18 +05:30
}
```
## Delete a pipeline schedule variable
Delete the variable of a pipeline schedule.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
```
| Attribute | Type | required | Description |
|------------------------|----------------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `pipeline_schedule_id` | integer | yes | The pipeline schedule ID |
2018-03-17 18:26:18 +05:30
| `key` | string | yes | The `key` of a variable |
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
2018-03-17 18:26:18 +05:30
```
```json
{
"key": "NEW_VARIABLE",
"value": "updated value"
}
```