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

176 lines
7.1 KiB
Markdown
Raw Normal View History

2020-07-28 23:09:34 +05:30
---
stage: Release
group: Release Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
type: concepts, howto
---
2020-05-24 23:13:21 +05:30
# Freeze Periods API
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0.
2020-07-28 23:09:34 +05:30
You can use the Freeze Periods API to manipulate GitLab's [Freeze Period](../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze) entries.
2020-05-24 23:13:21 +05:30
## Permissions and security
Only users with Maintainer [permissions](../user/permissions.md) can
interact with the Freeze Period API endpoints.
## List Freeze Periods
Paginated list of Freeze Periods, sorted by `created_at` in ascending order.
```plaintext
GET /projects/:id/freeze_periods
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
Example request:
```shell
curl --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" "https://gitlab.example.com/api/v4/projects/19/freeze_periods"
```
Example response:
```json
[
{
"id":1,
"freeze_start":"0 23 * * 5",
"freeze_end":"0 8 * * 1",
"cron_timezone":"UTC",
"created_at":"2020-05-15T17:03:35.702Z",
"updated_at":"2020-05-15T17:06:41.566Z"
}
]
```
## Get a Freeze Period by a `freeze_period_id`
Get a Freeze Period for the given `freeze_period_id`.
```plaintext
GET /projects/:id/freeze_periods/:freeze_period_id
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `freeze_period_id` | string | yes | The database ID of the Freeze Period. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1"
```
Example response:
```json
{
"id":1,
"freeze_start":"0 23 * * 5",
"freeze_end":"0 8 * * 1",
"cron_timezone":"UTC",
"created_at":"2020-05-15T17:03:35.702Z",
"updated_at":"2020-05-15T17:06:41.566Z"
}
```
## Create a Freeze Period
Create a Freeze Period.
```plaintext
POST /projects/:id/freeze_periods
```
| Attribute | Type | Required | Description |
| -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `freeze_start` | string | yes | Start of the Freeze Period in [cron](https://crontab.guru/) format. |
| `freeze_end` | string | yes | End of the Freeze Period in [cron](https://crontab.guru/) format. |
| `cron_timezone` | string | no | The timezone for the cron fields, defaults to UTC if not provided. |
Example request:
```shell
curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" \
--data '{ "freeze_start": "0 23 * * 5", "freeze_end": "0 7 * * 1", "cron_timezone": "UTC" }' \
--request POST https://gitlab.example.com/api/v4/projects/19/freeze_periods
```
Example response:
```json
{
"id":1,
"freeze_start":"0 23 * * 5",
"freeze_end":"0 7 * * 1",
"cron_timezone":"UTC",
"created_at":"2020-05-15T17:03:35.702Z",
"updated_at":"2020-05-15T17:03:35.702Z"
}
```
## Update a Freeze Period
Update a Freeze Period for the given `freeze_period_id`.
```plaintext
PUT /projects/:id/freeze_periods/:tag_name
```
| Attribute | Type | Required | Description |
| ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `freeze_period_id` | integer or string | yes | The database ID of the Freeze Period. |
| `freeze_start` | string | no | Start of the Freeze Period in [cron](https://crontab.guru/) format. |
| `freeze_end` | string | no | End of the Freeze Period in [cron](https://crontab.guru/) format. |
| `cron_timezone` | string | no | The timezone for the cron fields. |
Example request:
```shell
curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" \
--data '{ "freeze_end": "0 8 * * 1" }' \
--request PUT https://gitlab.example.com/api/v4/projects/19/freeze_periods/1
```
Example response:
```json
{
"id":1,
"freeze_start":"0 23 * * 5",
"freeze_end":"0 8 * * 1",
"cron_timezone":"UTC",
"created_at":"2020-05-15T17:03:35.702Z",
"updated_at":"2020-05-15T17:06:41.566Z"
}
```
## Delete a Freeze Period
Delete a Freeze Period for the given `freeze_period_id`.
```plaintext
DELETE /projects/:id/freeze_periods/:freeze_period_id
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `freeze_period_id` | string | yes | The database ID of the Freeze Period. |
Example request:
```shell
curl --request DELETE --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1"
```