summaryrefslogtreecommitdiff
path: root/doc/api/freeze_periods.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/freeze_periods.md')
-rw-r--r--doc/api/freeze_periods.md168
1 files changed, 168 insertions, 0 deletions
diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md
new file mode 100644
index 00000000000..ee5e657c945
--- /dev/null
+++ b/doc/api/freeze_periods.md
@@ -0,0 +1,168 @@
+# Freeze Periods API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0.
+
+You can use the Freeze Periods API to manipulate GitLab's [Freeze Period](../user/project/releases/index.md#set-a-deploy-freeze) entries.
+
+## 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"
+
+```