Merge branch 'pw-ctrt-1-deployment-approvals' into 'master'

CTRT-1 deployment approvals

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130781



Merged-by: Diana Logan <dlogan@gitlab.com>
Approved-by: Diana Logan <dlogan@gitlab.com>
Reviewed-by: Phillip Wells <pwells@gitlab.com>
Co-authored-by: phillipwells <pwells@gitlab.com>

doc/ci/environments/deployment_approvals.md

@@ -8,32 +8,24 @@ description: Require approvals prior to deploying to a Protected Environment
 # Deployment approvals **(PREMIUM ALL)**
 > - [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.
-It may be useful to require additional approvals before deploying to certain protected environments (for example, production). This pre-deployment approval requirement is useful to accommodate testing, security, or compliance processes that must happen before each deployment.
-When a protected environment requires one or more approvals, all deployments to that environment become blocked and wait for the required approvals from the `Allowed to Deploy` list before running.
-NOTE:
-See the [epic](https://gitlab.com/groups/gitlab-org/-/epics/6832) for planned features.
-
-## Prerequisites
-
-- Basic knowledge of [GitLab Environments and Deployments](index.md).
-- Basic knowledge of [Protected Environments](protected_environments.md).
-## Configure deployment approvals for a project
+> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. Feature flag `deployment_approvals` removed.
+You can require additional approvals for deployments to protected
+environments. Deployments are blocked until all required approvals are
+given.
+Use deployment approvals to accommodate testing,
+security, or compliance processes. For example, you might want to
+require approvals for deployments to production environments.
+## Configure deployment approvals
+You can require approvals for deployments to protected environments in
+a project.
 To configure deployment approvals for a project:
-1. [Create a deployment job](#create-a-deployment-job).
-1. [Require approvals for a protected environment](#require-approvals-for-a-protected-environment).
-
-### Create a deployment job
-
-Create a deployment job in the `.gitlab-ci.yml` file of the desired project. The job does **not** need to be manual (`when: manual`).
-
-Example:
+1. Create a deployment job in the `.gitlab-ci.yml` file of your project:
    ```yaml
    stages:
@@ -47,22 +39,15 @@ Example:
        name: ${CI_JOB_NAME}
    ```
-### Require approvals for a protected environment
-There are two ways to configure the approval requirements:
-- [Unified approval setting](#unified-approval-setting-deprecated) ... You can define who can execute **and** approve deployments.
-  This is useful when there is no separation of duties between executors and approvers in your organization.
-- [Multiple approval rules](#multiple-approval-rules) ... You can define who can execute **or** approve deployments.
-  This is useful when there is a separation of duties between executors and approvers in your organization.
-
-NOTE:
-Multiple approval rules is a more flexible option than the unified approval setting, thus both configurations shouldn't
-co-exist and multiple approval rules takes the precedence over the unified approval setting if it happens.
+   The job does not need to be manual (`when: manual`).
+1. Add the required [approval rules](#multiple-approval-rules).
+The environments in your project require approval before deployment.
 <!--- start_remove The following content will be removed on remove_date: '2024-05-22' -->
-#### Unified approval setting (deprecated)
+### Unified approval setting (deprecated)
 > - UI configuration [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/378447) in GitLab
 >   15.11.
@@ -94,7 +79,7 @@ Maintainer role.
 <!--- end_remove -->
-#### Multiple approval rules
+### Multiple approval rules
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) in GitLab 14.10 with a flag named `deployment_approval_rules`. Disabled by default.
 > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) in GitLab 15.0. [Feature flag `deployment_approval_rules`](https://gitlab.com/gitlab-org/gitlab/-/issues/345678) removed.
@@ -128,7 +113,7 @@ NOTE:
 To protect, update, or unprotect an environment, you must have at least the
 Maintainer role.
-#### Migrate to multiple approval rules
+### Migrate to multiple approval rules
 You can migrate a protected environment from unified approval rules to multiple
 approval rules. Unified approval rules allow all entities that can deploy to an
@@ -265,9 +250,9 @@ Use the [Deployments API](../../api/deployments.md#get-a-specific-deployment) to
 - When the [multiple approval rules](#multiple-approval-rules) is configured:
   - The `approval_summary` field contains the current approval status per rule.
-## Related features
-For details about other GitLab features aimed at protecting deployments, see [safe deployments](deployment_safety.md).
+## Related topics
+- [Deployment approvals feature epic](https://gitlab.com/groups/gitlab-org/-/epics/6832)
 <!-- ## Troubleshooting