Add documentation for group-level protected environments

doc/api/group_protected_environments.md

+---
+stage: Release
+group: Release
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+type: concepts, howto
+---
+
+# Group-level protected environments API **(PREMIUM)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0.
+> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../ci/environments/protected_environments.md#enable-or-disable-group-level-protected-environments). **(FREE SELF)**
+
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](../user/feature_flags.md#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
+
+Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments),
+
+## Valid access levels
+
+The access levels are defined in the `ProtectedEnvironment::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method.
+Currently, these levels are recognized:
+
+```plaintext
+30 => Developer access
+40 => Maintainer access
+60 => Admin access
+```
+
+## List group-level protected environments
+
+Gets a list of protected environments from a group.
+
+```shell
+GET /groups/:id/protected_environments
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/"
+```
+
+Example response:
+
+```json
+[
+   {
+      "name":"production",
+      "deploy_access_levels":[
+         {
+            "access_level":40,
+            "access_level_description":"Maintainers",
+            "user_id":null,
+            "group_id":null
+         }
+      ]
+   }
+]
+```
+
+## Get a single protected environment
+
+Gets a single protected environment.
+
+```shell
+GET /groups/:id/protected_environments/:name
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. |
+| `name`    | string | yes    | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).|
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/production"
+```
+
+Example response:
+
+```json
+{
+   "name":"production",
+   "deploy_access_levels":[
+      {
+         "access_level":40,
+         "access_level_description":"Maintainers",
+         "user_id":null,
+         "group_id":null
+      }
+   ]
+}
+```
+
+## Protect an environment
+
+Protects a single environment.
+
+```shell
+POST /groups/:id/protected_environments
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. |
+| `name`    | string | yes    | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).|
+| `deploy_access_levels`          | array          | yes | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. |
+
+The assignable `user_id` are the users who belong to the given group with the Maintainer role (or above).
+The assignable `group_id` are the sub-groups under the given group.
+
+```shell
+curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments"
+```
+
+Example response:
+
+```json
+{
+   "name":"production",
+   "deploy_access_levels":[
+      {
+         "access_level":40,
+         "access_level_description":"protected-access-group",
+         "user_id":null,
+         "group_id":9899826
+      }
+   ]
+}
+```
+
+## Unprotect environment
+
+Unprotects the given protected environment.
+
+```shell
+DELETE /groups/:id/protected_environments/:name
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. |
+| `name`    | string | yes    | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).|
+
+```shell
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/staging"
+```
+
+The response should return a 200 code.

doc/ci/environments/protected_environments.md

@@ -154,6 +154,129 @@ be re-entered if the environment is re-protected.
 
 For more information, see [Deployment safety](deployment_safety.md).
 
+## Group-level protected environments
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0.
+> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-level-protected-environments). **(FREE SELF)**
+
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
+
+Typically, large enterprise organizations have an explicit permission boundary
+between [developers and operators](https://about.gitlab.com/topics/devops/).
+Developers build and test their code, and operators deploy and monitor the
+application. With group-level protected environments, the permission of each
+group is carefully configured in order to prevent unauthorized access and
+maintain proper separation of duty. Group-level protected environments
+extend the [project-level protected environments](#protecting-environments)
+to the group-level.
+
+The permissions of deployments can be illustrated in the following table:
+
+| Environment | Developer  | Operator | Category |
+|-------------|------------|----------|----------|
+| Development | Allowed    | Allowed  | Lower environment  |
+| Testing     | Allowed    | Allowed  | Lower environment  |
+| Staging     | Disallowed | Allowed  | Higher environment |
+| Production  | Disallowed | Allowed  | Higher environment |
+
+_(Reference: [Deployment environments on Wikipedia](https://en.wikipedia.org/wiki/Deployment_environment))_
+
+### Group-level protected environments names
+
+Contrary to project-level protected environments, group-level protected
+environments use the [deployment tier](index.md#deployment-tier-of-environments)
+as their name.
+
+A group may consist of many project environments that have unique names.
+For example, Project-A has a `gprd` environment and Project-B has a `Production`
+environment, so protecting a specific environment name doesn't scale well.
+By using deployment tiers, both are recognized as `production` deployment tier
+and are protected at the same time.
+
+### Configure group-level memberships
+
+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 added as a
+maintainer to 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 assigned the [maintainer role](../../user/permissions.md)
+  (or above) to the top-level group. They can maintain CI/CD configurations for
+  the higher environments (such as production) in the group-level settings page,
+  wnich includes group-level protected environments,
+  [group-level runners](../runners/README.md#group-runners),
+  [group-level clusters](../../user/group/clusters/index.md), etc. Those
+  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 assigned the [developer role](../../user/permissions.md)
+  (or below) at the top-level group, or explicitly assigned to a child project
+  as maintainers. 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.
+- For sub-groups and child projects:
+  - Regarding [sub-groups](../../user/group/subgroups/index.md), if a higher
+    group has configured the group-level protected environment, the lower groups
+    cannot override it.
+  - [Project-level protected environments](#protecting-environments) can be
+    combined with the group-level setting. If both group-level and project-level
+    environment configurations exist, the user must be allowed in **both**
+    rulesets in order to run a deployment job.
+  - Within a project or a sub-group of the top-level group, developers can be
+    safely assigned the Maintainer role to tune their lower environments (such
+    as `testing`).
+
+Having this configuration in place:
+
+- If a user is about to run a deployment job in a project and allowed to deploy
+  to the environment, the deployment job proceeds.
+- If a user is about to run a deployment job in a project but disallowed to
+  deploy to the environment, the deployment job fails with an error message.
+
+### Protect a group-level environment
+
+To protect a group-level environment:
+
+1. Make sure your environments have the correct
+   [`deployment_tier`](index.md#deployment-tier-of-environments) defined in
+   `gitlab-ci.yml`.
+1. Configure the group-level protected environments via the
+   [REST API](../../api/group_protected_environments.md).
+
+NOTE:
+Configuration [via the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/325249)
+is scheduled for a later release.
+
+### Enable or disable Group-level protected environments **(FREE SELF)**
+
+Group-level protected environments is under development and not ready for production use. It is
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:group_level_protected_environments)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:group_level_protected_environments)
+```
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues