BigW Consortium Gitlab

pipeline_schedules.md 12.8 KB
Newer Older
Shinya Maeda committed
1 2
# Pipeline schedules

Shinya Maeda committed
3
You can read more about [pipeline schedules](../user/project/pipelines/schedules.md).
Shinya Maeda committed
4

Shinya Maeda committed
5
## Get all pipeline schedules
Shinya Maeda committed
6

Shinya Maeda committed
7
Get a list of the pipeline schedules of a project.
Shinya Maeda committed
8 9 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 committed
17

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

```json
[
    {
25 26
        "id": 13,
        "description": "Test schedule pipeline",
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 committed
31
        "active": true,
32 33
        "created_at": "2017-05-19T13:31:08.849Z",
        "updated_at": "2017-05-19T13:40:17.727Z",
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 committed
40
            "web_url": "https://gitlab.example.com/root"
Shinya Maeda committed
41 42 43 44 45
        }
    }
]
```

Shinya Maeda committed
46
## Get a single pipeline schedule
Shinya Maeda committed
47

Shinya Maeda committed
48
Get the pipeline schedule of a project.
Shinya Maeda committed
49 50 51 52 53 54 55 56 57 58

```
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      |
| `pipeline_schedule_id` | integer | yes      | The pipeline schedule id           |

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

```json
{
65 66
    "id": 13,
    "description": "Test schedule pipeline",
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 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 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 committed
86
        "web_url": "https://gitlab.example.com/root"
87 88 89 90 91 92 93
    },
    "variables": [
        {
            "key": "TEST_VARIABLE_1",
            "value": "TEST_1"
        }
    ]
Shinya Maeda committed
94 95 96
}
```

Shinya Maeda committed
97
## Create a new pipeline schedule
Shinya Maeda committed
98

Shinya Maeda committed
99
Create a new pipeline schedule of a project.
Shinya Maeda committed
100 101 102 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         |
| `cron ` | string  | yes      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
111 112
| `cron_timezone ` | string  | no      | The timezone supproted 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 committed
113

Shinya Maeda committed
114 115
```sh
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 committed
116 117 118 119
```

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

Shinya Maeda committed
141
## Edit a pipeline schedule
Shinya Maeda committed
142

Shinya Maeda committed
143
Updates the pipeline schedule  of a project. Once the update is done, it will be rescheduled automatically.
Shinya Maeda committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158

```
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      |
| `pipeline_schedule_id`  | integer | yes      | The pipeline schedule id           |
| `description` | string  | no      | The description of pipeline schedule         |
| `ref` | string  | no      | The branch/tag name will be triggered         |
| `cron ` | string  | no      | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron))       |
| `cron_timezone ` | string  | no      | The timezone supproted 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 committed
159 160
```sh
curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
Shinya Maeda committed
161 162 163 164
```

```json
{
165 166
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda committed
167 168
    "ref": "master",
    "cron": "0 2 * * *",
169 170
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
Shinya Maeda committed
171
    "active": true,
172 173 174 175 176 177 178 179
    "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 committed
180 181 182 183 184 185
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
Shinya Maeda committed
186
        "web_url": "https://gitlab.example.com/root"
Shinya Maeda committed
187 188 189 190 191 192
    }
}
```

## Take ownership of a pipeline schedule

Shinya Maeda committed
193
Update the owner of the pipeline schedule of a project.
Shinya Maeda committed
194 195 196 197 198 199 200 201 202 203

```
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      |
| `pipeline_schedule_id`  | integer | yes      | The pipeline schedule id           |

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

```json
{
210 211
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda committed
212 213
    "ref": "master",
    "cron": "0 2 * * *",
214 215
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
Shinya Maeda committed
216
    "active": true,
217 218 219 220 221 222 223 224
    "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 committed
225 226 227 228 229 230
    "owner": {
        "name": "shinya",
        "username": "maeda",
        "id": 50,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
Shinya Maeda committed
231
        "web_url": "https://gitlab.example.com/maeda"
Shinya Maeda committed
232 233 234 235 236 237
    }
}
```

## Delete a pipeline schedule

Shinya Maeda committed
238
Delete the pipeline schedule of a project.
Shinya Maeda committed
239 240 241 242 243 244 245 246 247 248

```
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      |
| `pipeline_schedule_id`   | integer | yes      | The pipeline schedule id           |

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

```json
{
255 256
    "id": 13,
    "description": "Test schedule pipeline",
Shinya Maeda committed
257 258
    "ref": "master",
    "cron": "0 2 * * *",
259 260
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
Shinya Maeda committed
261
    "active": true,
262 263 264 265 266 267 268 269
    "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 committed
270 271 272 273 274 275
    "owner": {
        "name": "shinya",
        "username": "maeda",
        "id": 50,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
Shinya Maeda committed
276
        "web_url": "https://gitlab.example.com/maeda"
Shinya Maeda committed
277 278 279
    }
}
```
280

Shinya Maeda committed
281 282 283 284
## Pipeline schedule variable

> [Introduced][ce-34518] in GitLab 10.0.

285 286 287 288 289 290 291 292
## Create a new pipeline schedule variable

Create a new variable of a pipeline schedule.

```
POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables
```

293 294 295 296 297 298
| 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      |
| `pipeline_schedule_id` | integer        | yes      | The pipeline schedule id |
| `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 |
299 300 301 302 303 304 305

```sh
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 committed
306 307
    "key": "NEW_VARIABLE",
    "value": "new value"
308 309 310 311 312 313 314 315 316 317 318
}
```

## Edit a pipeline schedule variable

Updates the variable of a pipeline schedule.

```
PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
```

319 320 321 322 323 324
| 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      |
| `pipeline_schedule_id` | integer        | yes      | The pipeline schedule id |
| `key`                  | string         | yes      | The `key` of a variable   |
| `value`                | string         | yes      | The `value` of a variable |
325 326 327 328 329 330 331

```sh
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 committed
332 333
    "key": "NEW_VARIABLE",
    "value": "updated value"
334 335 336 337 338 339 340 341 342 343 344
}
```

## Delete a pipeline schedule variable

Delete the variable of a pipeline schedule.

```
DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
```

345 346 347 348 349
| 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      |
| `pipeline_schedule_id` | integer        | yes      | The pipeline schedule id |
| `key`                  | string         | yes      | The `key` of a variable |
350 351 352 353 354 355

```sh
curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
```

```json
356 357 358 359
{
    "key": "NEW_VARIABLE",
    "value": "updated value"
}
360
```
Shinya Maeda committed
361 362

[ce-34518]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34518