2 files changed, 102 insertions, 4 deletions
diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md
index 45af78aa036..2a5927a96c2 100644
--- a/doc/ci/environments/deployment_approvals.md
+++ b/doc/ci/environments/deployment_approvals.md
@@ -15,7 +15,7 @@ This feature is in a [Beta](../../policy/alpha-beta-support.md#beta-features) st
 
 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 before running.
+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.
@@ -52,6 +52,19 @@ Example:
 
 ### Require approvals for a protected environment
 
+There are two ways to configure the approval requirements:
+
+- [Unified approval setting](#unified-approval-setting) ... 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.
+
+#### Unified approval setting
+
 NOTE:
 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.
 
@@ -77,6 +90,35 @@ NOTE:
 To protect, update, or unprotect an environment, you must have at least the
 Maintainer role.
 
+#### 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.
+
+1. Using the [REST API](../../api/group_protected_environments.md#protect-an-environment).
+   1. `deploy_access_levels` represents which entity can execute the deployment job.
+   1. `approval_rules` represents which entity can approve the deployment job.
+
+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:
+
+```shell
+curl --header 'Content-Type: application/json' --request POST \
+     --data '{"name": "production", "deploy_access_levels": [{"group_id": 138}], "approval_rules": [{"group_id": 134}, {"group_id": 135, "required_approvals": 2}]}' \
+     --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/groups/128/protected_environments"
+```
+
+With this setup:
+
+- The operator group (`group_id: 138`) has permission to execute the deployment jobs to the `production` environment in the organization (`group_id: 128`).
+- The QA tester group (`group_id: 134`) and security group (`group_id: 135`) have permission to approve the deployment jobs to the `production` environment in the organization (`group_id: 128`).
+- Unless two approvals from security group and one approval from QA tester group have been collected, the operator group can't execute the deployment jobs.
+
+NOTE:
+To protect, update, or unprotect an environment, you must have at least the
+Maintainer role.
+
 ## Approve or reject a deployment
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342180/) in GitLab 14.9
@@ -99,6 +141,10 @@ To approve or reject a deployment to a protected environment using the UI:
 1. In the deployment's row, select **Approval options** (**{thumb-up}**).
 1. Select **Approve** or **Reject**.
 
+NOTE:
+This feature might not work as expected when [Multiple approval rules](#multiple-approval-rules) is configured.
+See the [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/355708) for planned improvement.
+
 ### Approve or reject a deployment using the API
 
 Prerequisites:
@@ -127,11 +173,14 @@ curl --data "status=approved&comment=Looks good to me" \
 
 ### Using the API
 
-Use the [Deployments API](../../api/deployments.md) to see deployments.
+Use the [Deployments API](../../api/deployments.md#get-a-specific-deployment) 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.
+- When the [unified approval setting](#unified-approval-setting) is configured:
+  - The `pending_approval_count` field indicates how many approvals are remaining to run a deployment.
+  - The `approvals` field contains the deployment's approvals.
+- When the [multiple approval rules](#multiple-approval-rules) is configured:
+  - The `approval_summary` field contains the current approval status per rule.
 
 ## Related features
 
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index c2612b6ff16..3822b32181f 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -558,6 +558,55 @@ Because `stop_review_app` is set to `auto_stop_in: 1 week`,
 if a merge request is inactive for more than a week,
 GitLab automatically triggers the `stop_review_app` job to stop the environment.
 
+#### Multiple stop actions for an environment
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22456) in GitLab 14.10 [with a flag](../../administration/feature_flags.md) named `environment_multiple_stop_actions`. Disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `environment_multiple_stop_actions`.
+On GitLab.com, this feature is not available. We are enabling in phases and the status can be tracked in [issue 358911](https://gitlab.com/gitlab-org/gitlab/-/issues/358911).
+
+This feature is useful when you need to perform multiple **parallel** stop actions on an environment.
+
+To configure multiple stop actions on an environment, specify the [`on_stop`](../yaml/index.md#environmenton_stop)
+keyword across multiple [deployment jobs](../jobs/index.md#deployment-jobs) for the same `environment`, as defined in the `.gitlab-ci.yml` file.
+
+When an environment is stopped, the matching `on_stop` actions from *successful deployment jobs* alone are run in parallel in no particular order.
+
+In the following example, for the `test` environment there are two deployment jobs `deploy-to-cloud-a`
+and `deploy-to-cloud-b`.
+
+```yaml
+deploy-to-cloud-a:
+  script: echo "Deploy to cloud a"
+  environment:
+    name: test
+    on_stop: teardown-cloud-a
+
+deploy-to-cloud-b:
+  script: echo "Deploy to cloud b"
+  environment:
+    name: test
+    on_stop: teardown-cloud-b
+
+teardown-cloud-a:
+  script: echo "Delete the resources in cloud a"
+  environment:
+    name: test
+    action: stop
+  when: manual
+
+teardown-cloud-b:
+  script: echo "Delete the resources in cloud b"
+  environment:
+    name: test
+    action: stop
+  when: manual
+```
+
+When the environment is stopped, the system runs `on_stop` actions
+`teardown-cloud-a` and `teardown-cloud-b` in parallel.
+
 #### View a deployment's scheduled stop time
 
 You can view a deployment's expiration date in the GitLab UI.