Skip to content

G
gitlab-ce
Commit 36637213 authored by Sean Carroll's avatar Sean Carroll Committed by Amy Qualls
Browse files
Options

Freeze Period documentation 

Part of https://gitlab.com/gitlab-org/gitlab/-/issues/214328

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29384
parent 9c1eac5d
Hide whitespace changes
Inline Side-by-side
Showing with 202 additions and 0 deletions
doc/api/api_resources.md
View file @ 36637213
......@@ -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 0 → 100644
View file @ 36637213
# 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
View file @ 36637213
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7