pipeline_schedules.md 14.5 KB
Newer Older
1
# Pipeline schedules API
Shinya Maeda's avatar
Shinya Maeda committed
2

3
You can read more about [pipeline schedules](../ci/pipelines/schedules.md).
Shinya Maeda's avatar
Shinya Maeda committed
4

Shinya Maeda's avatar
Shinya Maeda committed
5
## Get all pipeline schedules
Shinya Maeda's avatar
Shinya Maeda committed
6

Shinya Maeda's avatar
Shinya Maeda committed
7
Get a list of the pipeline schedules of a project.
Shinya Maeda's avatar
Shinya Maeda committed
8

9
```plaintext
Shinya Maeda's avatar
Shinya Maeda committed
10 11 12 13 14 15
GET /projects/:id/pipeline_schedules
```

| Attribute | Type    | required | Description         |
|-----------|---------|----------|---------------------|
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
16
| `scope`   | string  | no       | The scope of pipeline schedules, one of: `active`, `inactive` |
Shinya Maeda's avatar
Shinya Maeda committed
17

18
```shell
Shinya Maeda's avatar
Shinya Maeda committed
19
curl --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
Shinya Maeda's avatar
Shinya Maeda committed
20 21 22 23 24
```

```json
[
    {
25 26
        "id": 13,
        "description": "Test schedule pipeline",
Shinya Maeda's avatar
Shinya Maeda committed
27
        "ref": "master",
28 29 30
        "cron": "* * * * *",
        "cron_timezone": "Asia/Tokyo",
        "next_run_at": "2017-05-19T13:41:00.000Z",
Shinya Maeda's avatar
Shinya Maeda committed
31
        "active": true,
32 33
        "created_at": "2017-05-19T13:31:08.849Z",
        "updated_at": "2017-05-19T13:40:17.727Z",
Shinya Maeda's avatar
Shinya Maeda committed
34 35 36 37 38 39
        "owner": {
            "name": "Administrator",
            "username": "root",
            "id": 1,
            "state": "active",
            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
Shinya Maeda's avatar
Shinya Maeda committed
40
            "web_url": "https://gitlab.example.com/root"
Shinya Maeda's avatar
Shinya Maeda committed
41 42 43 44 45
        }
    }
]
```

Shinya Maeda's avatar
Shinya Maeda committed
46
## Get a single pipeline schedule
Shinya Maeda's avatar
Shinya Maeda committed
47

Shinya Maeda's avatar
Shinya Maeda committed
48
Get the pipeline schedule of a project.
Shinya Maeda's avatar
Shinya Maeda committed
49

50
```plaintext
Shinya Maeda's avatar
Shinya Maeda committed
51 52 53 54 55 56
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](README.md#namespaced-path-encoding) owned by the authenticated user      |
57
| `pipeline_schedule_id` | integer | yes      | The pipeline schedule ID           |
Shinya Maeda's avatar
Shinya Maeda committed
58

59
```shell
Shinya Maeda's avatar
Shinya Maeda committed
60
curl --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
Shinya Maeda's avatar
Shinya Maeda committed
61 62 63 64
```

```json
{
65 66
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda's avatar
Shinya Maeda committed
67
    "ref": "master",
68 69 70
    "cron": "* * * * *",
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T13:41:00.000Z",
Shinya Maeda's avatar
Shinya Maeda committed
71
    "active": true,
72 73 74 75 76 77 78 79
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:40:17.727Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "master",
        "status": "pending"
    },
Shinya Maeda's avatar
Shinya Maeda committed
80 81 82 83 84 85
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
Shinya Maeda's avatar
Shinya Maeda committed
86
        "web_url": "https://gitlab.example.com/root"
87 88 89 90
    },
    "variables": [
        {
            "key": "TEST_VARIABLE_1",
91
            "variable_type": "env_var",
92 93 94
            "value": "TEST_1"
        }
    ]
Shinya Maeda's avatar
Shinya Maeda committed
95 96 97
}
```

Shinya Maeda's avatar
Shinya Maeda committed
98
## Create a new pipeline schedule
Shinya Maeda's avatar
Shinya Maeda committed
99

Shinya Maeda's avatar
Shinya Maeda committed
100
Create a new pipeline schedule of a project.
Shinya Maeda's avatar
Shinya Maeda committed
101

102
```plaintext
Shinya Maeda's avatar
Shinya Maeda committed
103 104 105 106 107 108 109 110
POST /projects/:id/pipeline_schedules
```

| Attribute     | Type    | required | Description              |
|---------------|---------|----------|--------------------------|
| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
| `description` | string  | yes      | The description of pipeline schedule         |
| `ref` | string  | yes      | The branch/tag name will be triggered         |
111 112 113
| `cron` | string  | yes      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
| `cron_timezone` | string  | no      | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`)     |
| `active` | boolean  | no      | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) |
Shinya Maeda's avatar
Shinya Maeda committed
114

115
```shell
Shinya Maeda's avatar
Shinya Maeda committed
116
curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form description="Build packages" --form ref="master" --form cron="0 1 * * 5" --form cron_timezone="UTC" --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
Shinya Maeda's avatar
Shinya Maeda committed
117 118 119 120
```

```json
{
121
    "id": 14,
Shinya Maeda's avatar
Shinya Maeda committed
122 123 124 125
    "description": "Build packages",
    "ref": "master",
    "cron": "0 1 * * 5",
    "cron_timezone": "UTC",
126
    "next_run_at": "2017-05-26T01:00:00.000Z",
Shinya Maeda's avatar
Shinya Maeda committed
127
    "active": true,
128 129 130
    "created_at": "2017-05-19T13:43:08.169Z",
    "updated_at": "2017-05-19T13:43:08.169Z",
    "last_pipeline": null,
Shinya Maeda's avatar
Shinya Maeda committed
131 132 133 134 135 136
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
Shinya Maeda's avatar
Shinya Maeda committed
137
        "web_url": "https://gitlab.example.com/root"
Shinya Maeda's avatar
Shinya Maeda committed
138 139 140 141
    }
}
```

Shinya Maeda's avatar
Shinya Maeda committed
142
## Edit a pipeline schedule
Shinya Maeda's avatar
Shinya Maeda committed
143

144
Updates the pipeline schedule of a project. Once the update is done, it will be rescheduled automatically.
Shinya Maeda's avatar
Shinya Maeda committed
145

146
```plaintext
Shinya Maeda's avatar
Shinya Maeda committed
147 148 149 150 151 152
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](README.md#namespaced-path-encoding) owned by the authenticated user      |
153
| `pipeline_schedule_id`  | integer | yes      | The pipeline schedule ID           |
Shinya Maeda's avatar
Shinya Maeda committed
154 155
| `description` | string  | no      | The description of pipeline schedule         |
| `ref` | string  | no      | The branch/tag name will be triggered         |
156 157 158
| `cron` | string  | no      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
| `cron_timezone` | string  | no      | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`)      |
| `active` | boolean  | no      | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. |
Shinya Maeda's avatar
Shinya Maeda committed
159

160
```shell
Shinya Maeda's avatar
Shinya Maeda committed
161
curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
Shinya Maeda's avatar
Shinya Maeda committed
162 163 164 165
```

```json
{
166 167
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda's avatar
Shinya Maeda committed
168 169
    "ref": "master",
    "cron": "0 2 * * *",
170 171
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
Shinya Maeda's avatar
Shinya Maeda committed
172
    "active": true,
173 174 175 176 177 178 179 180
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:44:16.135Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "master",
        "status": "pending"
    },
Shinya Maeda's avatar
Shinya Maeda committed
181 182 183 184 185 186
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
Shinya Maeda's avatar
Shinya Maeda committed
187
        "web_url": "https://gitlab.example.com/root"
Shinya Maeda's avatar
Shinya Maeda committed
188 189 190 191 192 193
    }
}
```

## Take ownership of a pipeline schedule

Shinya Maeda's avatar
Shinya Maeda committed
194
Update the owner of the pipeline schedule of a project.
Shinya Maeda's avatar
Shinya Maeda committed
195

196
```plaintext
Shinya Maeda's avatar
Shinya Maeda committed
197 198 199 200 201 202
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](README.md#namespaced-path-encoding) owned by the authenticated user      |
203
| `pipeline_schedule_id`  | integer | yes      | The pipeline schedule ID           |
Shinya Maeda's avatar
Shinya Maeda committed
204

205
```shell
Shinya Maeda's avatar
Shinya Maeda committed
206
curl --request POST --header "PRIVATE-TOKEN: hf2CvZXB9w8Uc5pZKpSB" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/take_ownership"
Shinya Maeda's avatar
Shinya Maeda committed
207 208 209 210
```

```json
{
211 212
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda's avatar
Shinya Maeda committed
213 214
    "ref": "master",
    "cron": "0 2 * * *",
215 216
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
Shinya Maeda's avatar
Shinya Maeda committed
217
    "active": true,
218 219 220 221 222 223 224 225
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:46:37.468Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "master",
        "status": "pending"
    },
Shinya Maeda's avatar
Shinya Maeda committed
226 227 228 229 230 231
    "owner": {
        "name": "shinya",
        "username": "maeda",
        "id": 50,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
Shinya Maeda's avatar
Shinya Maeda committed
232
        "web_url": "https://gitlab.example.com/maeda"
Shinya Maeda's avatar
Shinya Maeda committed
233 234 235 236 237 238
    }
}
```

## Delete a pipeline schedule

Shinya Maeda's avatar
Shinya Maeda committed
239
Delete the pipeline schedule of a project.
Shinya Maeda's avatar
Shinya Maeda committed
240

241
```plaintext
Shinya Maeda's avatar
Shinya Maeda committed
242 243 244 245 246 247
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](README.md#namespaced-path-encoding) owned by the authenticated user      |
248
| `pipeline_schedule_id`   | integer | yes      | The pipeline schedule ID           |
Shinya Maeda's avatar
Shinya Maeda committed
249

250
```shell
Shinya Maeda's avatar
Shinya Maeda committed
251
curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
Shinya Maeda's avatar
Shinya Maeda committed
252 253 254 255
```

```json
{
256 257
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda's avatar
Shinya Maeda committed
258 259
    "ref": "master",
    "cron": "0 2 * * *",
260 261
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
Shinya Maeda's avatar
Shinya Maeda committed
262
    "active": true,
263 264 265 266 267 268 269 270
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:46:37.468Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "master",
        "status": "pending"
    },
Shinya Maeda's avatar
Shinya Maeda committed
271 272 273 274 275 276
    "owner": {
        "name": "shinya",
        "username": "maeda",
        "id": 50,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
Shinya Maeda's avatar
Shinya Maeda committed
277
        "web_url": "https://gitlab.example.com/maeda"
Shinya Maeda's avatar
Shinya Maeda committed
278 279 280
    }
}
```
281

282 283 284 285 286 287 288 289 290 291 292 293 294 295
## Run a scheduled pipeline immediately

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201786) in GitLab 12.8.

Trigger a new scheduled pipeline, which runs immediately. The next scheduled run
of this pipeline is not affected.

```text
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](README.md#namespaced-path-encoding) owned by the authenticated user |
296
| `pipeline_schedule_id` | integer        | yes        | The pipeline schedule ID                                                                                        |
297 298 299

Example request:

300
```shell
301 302 303 304 305 306 307 308 309 310 311
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/42/pipeline_schedules/1/play
```

Example response:

```json
{
  "message": "201 Created"
}
```

312
## Pipeline schedule variables
Shinya Maeda's avatar
Shinya Maeda committed
313

314
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/34518) in GitLab 10.0.
Shinya Maeda's avatar
Shinya Maeda committed
315

316 317 318 319
## Create a new pipeline schedule variable

Create a new variable of a pipeline schedule.

320
```plaintext
321 322 323
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables
```

Shinya Maeda's avatar
Shinya Maeda committed
324 325 326
| Attribute              | Type           | required | Description              |
|------------------------|----------------|----------|--------------------------|
| `id`                   | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
327
| `pipeline_schedule_id` | integer        | yes      | The pipeline schedule ID |
Shinya Maeda's avatar
Shinya Maeda committed
328 329
| `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 |
330
| `variable_type`        | string         | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
331

332
```shell
333 334 335 336 337
curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "key=NEW_VARIABLE" --form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables"
```

```json
{
Shinya Maeda's avatar
Shinya Maeda committed
338
    "key": "NEW_VARIABLE",
339
    "variable_type": "env_var",
Shinya Maeda's avatar
Shinya Maeda committed
340
    "value": "new value"
341 342 343 344 345 346 347
}
```

## Edit a pipeline schedule variable

Updates the variable of a pipeline schedule.

348
```plaintext
349 350 351
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
```

Shinya Maeda's avatar
Shinya Maeda committed
352 353 354
| Attribute              | Type           | required | Description              |
|------------------------|----------------|----------|--------------------------|
| `id`                   | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
355
| `pipeline_schedule_id` | integer        | yes      | The pipeline schedule ID |
Shinya Maeda's avatar
Shinya Maeda committed
356 357
| `key`                  | string         | yes      | The `key` of a variable   |
| `value`                | string         | yes      | The `value` of a variable |
358
| `variable_type`        | string         | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
359

360
```shell
361 362 363 364 365
curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "value=updated value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
```

```json
{
Shinya Maeda's avatar
Shinya Maeda committed
366 367
    "key": "NEW_VARIABLE",
    "value": "updated value"
368
    "variable_type": "env_var",
369 370 371 372 373 374 375
}
```

## Delete a pipeline schedule variable

Delete the variable of a pipeline schedule.

376
```plaintext
377 378 379
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
```

Shinya Maeda's avatar
Shinya Maeda committed
380 381 382
| Attribute              | Type           | required | Description              |
|------------------------|----------------|----------|--------------------------|
| `id`                   | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
383
| `pipeline_schedule_id` | integer        | yes      | The pipeline schedule ID |
Shinya Maeda's avatar
Shinya Maeda committed
384
| `key`                  | string         | yes      | The `key` of a variable |
385

386
```shell
387 388 389 390
curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
```

```json
Shinya Maeda's avatar
Shinya Maeda committed
391 392 393 394
{
    "key": "NEW_VARIABLE",
    "value": "updated value"
}
395
```