Merge branch '24295-deploy-freezes-for-environments-mvc-2' into 'master'

Freeze Period documentation

See merge request gitlab-org/gitlab!29384

doc/api/api_resources.md

@@ -26,6 +26,7 @@ The following API resources are available in the project context:
 | [Custom attributes](custom_attributes.md)                           | `/projects/:id/custom_attributes` (also available for groups and users)                                                                                                                               |
 | [Dependencies](dependencies.md) **(ULTIMATE)**                      | `/projects/:id/dependencies`                                                                                                                                                                          |
 | [Deploy keys](deploy_keys.md)                                       | `/projects/:id/deploy_keys` (also available standalone)                                                                                                                                               |
+| [Freeze Periods](freeze_periods.md)                                 | `/projects/:id/freeze_periods`                                                                                                                                                                        |
 | [Deployments](deployments.md)                                       | `/projects/:id/deployments`                                                                                                                                                                           |
 | [Discussions](discussions.md) (threaded comments)                   | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) |
 | [Environments](environments.md)                                     | `/projects/:id/environments`                                                                                                                                                                          |

doc/api/freeze_periods.md

+# 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`.
+
+```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"
+
+```

doc/user/project/releases/index.md

@@ -354,6 +354,39 @@ terminal.
 Read the [GitLab Releaser documentation](https://gitlab.com/gitlab-org/gitlab-releaser/-/tree/master/docs/index.md)
 for details.
 
+## Set a deploy freeze
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0.
+
+With a deploy freeze, you can prevent an unintended production release during a
+period of time you specify, whether a company event or public holiday. You can
+now rely on the enforcement of policies that are typically outside the scope of
+GitLab to reduce uncertainty and risk when automating deployments.
+
+Deploy freeze periods are set at the Project level, and may be created and
+managed using the [Freeze Periods API](../../../api/freeze_periods.md).
+Each Freeze Period has a `freeze_start` and a `freeze_end`, which are defined
+as [crontab](https://crontab.guru/) entries. If a project contains multiple
+freeze periods, all will apply, and should they overlap, the freeze covers the
+complete overlapped period.
+
+During pipeline processing, GitLab CI creates an environment variable named
+`$CI_ENVIRONMENT_FROZEN` if the currently executing job is within a
+Freeze Period.
+
+To take advantage of this variable, create a `rules` entry in your
+`gitlab-ci.yaml` to prevent the deployment job from executing.
+
+For example:
+
+```yaml
+deploy_to_production:
+  stage: deploy
+  script: deploy_to_prod.sh
+  rules:
+    - if: $CI_ENVIRONMENT_FROZEN == null
+```
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues