Merge branch 'docs/restructure-ci-envs-and-deployment' into 'master'

Refactor and restructure environments page

See merge request gitlab-org/gitlab-ce!26400

doc/ci/README.md

@@ -44,13 +44,13 @@ With basic knowledge of how GitLab CI/CD works, the following documentation exte
 into more features:
 
 | Topic                                                                                                                     | Description                                                                                |
-|:--------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------|
+|:--------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------|
 | [Creating and using CI/CD pipelines](pipelines.md)                                                                        | Understand, visualize, create, and use CI/CD pipelines.                                    |
 | [CI/CD Variables](variables/README.md)                                                                                    | How environment variables can be configured and made available in pipelines.               |
 | [Where variables can be used](variables/where_variables_can_be_used.md)                                                   | A deeper look into where and how CI/CD variables can be used.                              |
 | [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions      | Learn about the access levels a user can have for performing certain CI actions.           |
 | [Configuring GitLab Runners](runners/README.md)                                                                           | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/).            |
-| [Introduction to environments and deployments](environments.md)                                                           | Learn how to separate your jobs into environments and use them for different purposes like testing, building and, deploying. |
+| [Environments and deployments](environments.md)                                                                           | Deploy the output of jobs into environments for reviewing, staging, and production.        |
 | [Job artifacts](../user/project/pipelines/job_artifacts.md)                                                               | Learn about the output of jobs.                                                            |
 | [Cache dependencies in GitLab CI/CD](caching/index.md)                                                                    | Discover how to speed up pipelines using caching.                                          |
 | [Using Git submodules with GitLab CI](git_submodules.md)                                                                  | How to run your CI jobs when using Git submodules.                                         |
@@ -64,7 +64,6 @@ into more features:
 | [Review Apps](review_apps/index.md)                                                                                       | Configure GitLab CI/CD to preview code changes in a per-branch basis.                      |
 | [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]**                                 | Check the current health and status of each CI/CD environment running on Kubernetes.       |
 | [GitLab CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html) **[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
-| [Protected environments](https://docs.gitlab.com/ce/ci/environments/protected_environments.html) **[PREMIUM]**            | Ensure that only people with the right privileges can deploy to an environment.                                              |
 
 ### GitLab Pages
 

doc/ci/environments/protected_environments.md

+# Protected Environments **[PREMIUM]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
+
+## Overview
+
+[Environments](../environments.md) can be used for different reasons:
+
+- Some of them are just for testing.
+- Others are for production.
+
+Because deploy jobs can be raised by different users with different roles, it is important that
+specific environments are "protected" to avoid unauthorized people affecting them.
+
+By default, a protected environment does one thing: it ensures that only people
+with the right privileges can deploy to it, thus keeping it safe.
+
+NOTE: **Note**:
+A GitLab admin is always allowed to use environments, even if they are protected.
+
+To protect, update, or unprotect an environment, you need to have at least
+[Maintainer permissions](../../user/permissions.md).
+
+## Protecting environments
+
+To protect an environment:
+
+1. Navigate to your project's **Settings > CI/CD**.
+1. Expand the **Protected Environments** section.
+1. From the **Environment** dropdown menu, select the environment you want to protect.
+1. In the **Allowed to Deploy** dropdown menu, select the role, users, or  groups you want to have deploy access.
+   There are some considerations to have in mind:
+    - There are two roles to choose from:
+      - **Maintainers**: will allow access to all maintainers in the project.
+      - **Developers**: will allow access to all maintainers and all developers in the project.
+    - You can only select groups that are associated with the project.
+    - Only users that have at least Developer permission level will appear on
+      the **Allowed to Deploy** dropdown menu.
+1. Click the **Protect** button.
+
+The protected environment will now appear in the list of protected environments.
+
+## Modifying and unprotecting environments
+
+Maintainers can:
+
+- Update existing protected environments at any time by changing the access on **Allowed to deploy** dropdown menu.
+- Unprotect a protected environment by clicking the **Unprotect** button of the environment to unprotect.