diff options
Diffstat (limited to 'doc/ci/environments')
| -rw-r--r-- | doc/ci/environments/deployment_approvals.md | 27 | ||||
| -rw-r--r-- | doc/ci/environments/deployment_safety.md | 6 | ||||
| -rw-r--r-- | doc/ci/environments/img/environments_open_live_environment_v14_8.png | bin | 0 -> 33534 bytes | |||
| -rw-r--r-- | doc/ci/environments/index.md | 16 | ||||
| -rw-r--r-- | doc/ci/environments/protected_environments.md | 25 |
5 files changed, 49 insertions, 25 deletions
diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index d60e5704877..e320118c191 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -7,7 +7,8 @@ description: Require approvals prior to deploying to a Protected Environment # Deployment approvals **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 with a flag named `deployment_approvals`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 with a flag named `deployment_approvals`. Disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. WARNING: This feature is in an alpha stage and subject to change without prior notice. @@ -49,12 +50,19 @@ Example: name: ${CI_JOB_NAME} ``` -### Require approvals for a protected environment +### Require approvals for a protected environment NOTE: -At this time, only API-based configuration is available. UI-based configuration is planned for the near future. See [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/344675). +At this time, it is not possible to require approvals for an existing protected environment. The workaround is to unprotect the environment and configure approvals when re-protecting the environment. -Use the [Protected Environments API](../../api/protected_environments.md#protect-repository-environments) to create an environment with `required_approval_count` > 0. After this is set, all jobs deploying to this environment automatically go into a blocked state and wait for approvals before running. +There are two ways to configure approvals for a protected environment: + +1. Using the [UI](protected_environments.md#protecting-environments) + 1. Set the **Required approvals** field to 1 or more. +1. Using the [REST API](../../api/protected_environments.md#protect-repository-environments) + 2. Set the `required_approval_count` field to 1 or more. + +After this is configured, all jobs deploying to this environment automatically go into a blocked state and wait for approvals before running. Ensure that the number of required approvals is less than the number of users allowed to deploy. Example: @@ -65,8 +73,9 @@ curl --header 'Content-Type: application/json' --request POST \ "https://gitlab.example.com/api/v4/projects/22034114/protected_environments" ``` +NOTE: To protect, update, or unprotect an environment, you must have at least the -[Maintainer role](../../user/permissions.md). +Maintainer role. ## Approve or reject a deployment @@ -75,7 +84,7 @@ This functionality is currently only available through the API. UI is planned fo A blocked deployment is enqueued as soon as it receives the required number of approvals. A single rejection causes the deployment to fail. The creator of a deployment cannot approve it, even if they have permission to deploy. -Using the [Deployments API](../../api/deployments.md#approve-or-reject-a-blocked-deployment), users who are allowed to deploy to the protected environment can approve or reject a blocked deployment. +Using the [Deployments API](../../api/deployments.md#approve-or-reject-a-blocked-deployment), users who are allowed to deploy to the protected environment can approve or reject a blocked deployment. Example: @@ -95,7 +104,11 @@ curl --data "status=approved" \ #### Using the API -Use the [Deployments API](../../api/deployments.md) to see deployments. The `status` field indicates if a deployment is blocked. +Use the [Deployments API](../../api/deployments.md) to see deployments. + +- The `status` field indicates if a deployment is blocked. +- The `pending_approval_count` field indicates how many approvals are remaining to run a deployment. +- The `approvals` field contains the deployment's approvals. ## Related features diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 55c3c83338d..0e73dc4f7cd 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -26,7 +26,7 @@ If you are using a continuous deployment workflow and want to ensure that concur ## Restrict write access to a critical environment By default, environments can be modified by any team member that has at least the -[Developer role](../../user/permissions.md#project-members-permissions). +Developer role. If you want to restrict write access to a critical environment (for example a `production` environment), you can set up [protected environments](protected_environments.md). @@ -93,7 +93,7 @@ If you want to prevent deployments for a particular period, for example during a vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). During a deploy freeze period, no deployment can be executed. This is helpful to ensure that deployments do not happen unexpectedly. - + ## Setting appropriate roles to your project GitLab supports several different roles that can be assigned to your project members. See @@ -119,7 +119,7 @@ The other pipelines don't get the protected variable. You can also We recommend that you use protected variables on protected environments to make sure that the secrets aren't exposed unintentionally. You can also define production secrets on the [runner side](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). -This prevents other users with the [Maintainer role](../../user/permissions.md) from reading the secrets and makes sure +This prevents other users with the Maintainer role from reading the secrets and makes sure that the runner only runs on protected branches. For more information, see [pipeline security](../pipelines/index.md#pipeline-security-on-protected-branches). diff --git a/doc/ci/environments/img/environments_open_live_environment_v14_8.png b/doc/ci/environments/img/environments_open_live_environment_v14_8.png Binary files differnew file mode 100644 index 00000000000..daf531c83c4 --- /dev/null +++ b/doc/ci/environments/img/environments_open_live_environment_v14_8.png diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 794e4320fc6..63bdd279927 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -27,7 +27,7 @@ You can even access a [web terminal](#web-terminals-deprecated) for your environ Prerequisites: -- You must have at least the Reporter [role](../../user/permissions.md#project-members-permissions). +- You must have at least the Reporter role. To view a list of environments and deployments: @@ -308,10 +308,18 @@ Note the following: - If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update the environment URL. - If the script that runs in `stop_review` exists only in your repository and therefore can't use - `GIT_STRATEGY: none`, configure [pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md) + `GIT_STRATEGY: none`, configure [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) for these jobs. This ensures that runners can fetch the repository even after a feature branch is deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners). +NOTE: +For Windows runners, using `echo` to write to `.env` files may fail. Using the PowerShell `Add-Content`command +will help in such cases. For example: + +```powershell +Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" +``` + ## Track newly included merge requests per deployment GitLab can track newly included merge requests per deployment. @@ -372,7 +380,7 @@ places in GitLab: - In a merge request as a link:  - In the Environments view as a button: -  +  - In the Deployments view as a button:  @@ -440,7 +448,7 @@ the `stop_review` job might not be included in all pipelines that include the The job with [`action: stop` might not run](#the-job-with-action-stop-doesnt-run) if it's in a later stage than the job that started the environment. -If you can't use [pipelines for merge requests](../pipelines/merge_request_pipelines.md), +If you can't use [merge request pipelines](../pipelines/merge_request_pipelines.md), set the [`GIT_STRATEGY`](../runners/configure_runners.md#git-strategy) to `none` in the `stop_review` job. Then the [runner](https://docs.gitlab.com/runner/) doesn't try to check out the code after the branch is deleted. diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 78db2345de4..c7d1653aace 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -20,7 +20,7 @@ NOTE: GitLab administrators can use all environments, including protected environments. To protect, update, or unprotect an environment, you need to have at least the -[Maintainer role](../../user/permissions.md). +Maintainer role. ## Protecting environments @@ -38,6 +38,9 @@ To protect an environment: - You can select groups that are already associated with the project only. - Users must have at least the Developer role to appear in the **Allowed to deploy** list. +1. In the **Required approvals** list, select the number of approvals required to deploy to this environment. + - Ensure that this number is less than the number of users allowed to deploy. + - See [Deployment Approvals](deployment_approvals.md) for more information about this feature. 1. Select **Protect**. The protected environment now appears in the list of protected environments. @@ -94,7 +97,7 @@ Alternatively, you can use the API to protect an environment: 1. Use the API to add the group with protected environment access: ```shell - curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' \ + curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}], "required_approval_count": 0}' \ --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/projects/22034114/protected_environments" ``` @@ -103,12 +106,12 @@ The group now has access and can be seen in the UI. ## Environment access by group membership A user may be granted access to protected environments as part of [group membership](../../user/group/index.md). Users -with the Reporter [role](../../user/permissions.md) can only be granted access to protected environments with this +with the Reporter role can only be granted access to protected environments with this method. ## Deployment branch access -Users with the [Developer role](../../user/permissions.md) can be granted +Users with the Developer role can be granted access to a protected environment through any of these methods: - As an individual contributor, through a role. @@ -125,7 +128,7 @@ they have the following privileges: Users granted access to a protected environment, but not push or merge access to the branch deployed to it, are only granted access to deploy the environment. An individual in a -group with the Reporter [role](../../user/permissions.md), or in groups added to the project with the Reporter +group with the Reporter role, or in groups added to the project with the Reporter role, appears in the dropdown menu for deployment-only access. To add deployment-only access: @@ -136,7 +139,7 @@ To add deployment-only access: 1. Follow the steps in [Protecting Environments](#protecting-environments). Note that deployment-only access is the only possible access level for groups with the Reporter -[role](../../user/permissions.md). +role. ## Modifying and unprotecting environments @@ -194,14 +197,14 @@ and are protected at the same time. In an enterprise organization, with thousands of projects under a single group, ensuring that all of the [project-level protected environments](#protecting-environments) are properly configured is not a scalable solution. For example, a developer -might gain privileged access to a higher environment when they are given the [Maintainer role](../../user/permissions.md) +might gain privileged access to a higher environment when they are given the Maintainer role for a new project. Group-level protected environments can be a solution in this situation. To maximize the effectiveness of group-level protected environments, [group-level memberships](../../user/group/index.md) must be correctly configured: -- Operators should be given at least the [Maintainer role](../../user/permissions.md) +- Operators should be given at least the Maintainer role for the top-level group. They can maintain CI/CD configurations for the higher environments (such as production) in the group-level settings page, which includes group-level protected environments, @@ -210,8 +213,8 @@ configured: configurations are inherited to the child projects as read-only entries. This ensures that only operators can configure the organization-wide deployment ruleset. -- Developers should be given no more than the [Developer role](../../user/permissions.md) - for the top-level group, or explicitly given the [Maintainer role](../../user/permissions.md) for a child project +- Developers should be given no more than the Developer role + for the top-level group, or explicitly given the Maintainer role for a child project They do *NOT* have access to the CI/CD configurations in the top-level group, so operators can ensure that the critical configuration won't be accidentally changed by the developers. @@ -224,7 +227,7 @@ configured: environment configurations exist, to run a deployment job, the user must be allowed in **both** rulesets. - In a project or a subgroup of the top-level group, developers can be - safely assigned the [Maintainer role](../../user/permissions.md) to tune their lower environments (such + safely assigned the Maintainer role to tune their lower environments (such as `testing`). Having this configuration in place: |
