Add latest changes from gitlab-org/gitlab@master

1 files changed, 123 insertions, 0 deletions

diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
index b39c9fa2196..a6c9e4bd38e 100644
--- a/doc/ci/environments/protected_environments.md
+++ b/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