Refactor and restructure environments page

- Groups content into relevant sections.
- Content edited.

3 files changed, 452 insertions, 322 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 47810a8b7b6..5fe6c78701c 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -43,28 +43,27 @@ For complete control, you can manually configure GitLab CI/CD.
 With basic knowledge of how GitLab CI/CD works, the following documentation extends your knowledge
 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. |
-| [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.                                                                           |
-| [Pipelines for merge requests](merge_request_pipelines/index.md)                                                          | Create pipelines specifically for merge requests.                                                                            |
-| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md)                                                                    | Use SSH keys in your build environment.                                                                                      |
-| [Triggering pipelines through the API](triggers/README.md)                                                                | Use the GitLab API to trigger a pipeline.                                                                                    |
-| [Pipeline schedules](../user/project/pipelines/schedules.md)                                                              | Trigger pipelines on a schedule.                                                                                             |
-| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md)                                          | Integrate one or more Kubernetes clusters to your project.                                                                   |
-| [ChatOps](chatops/README.md)                                                                                              | Trigger CI jobs from chat, with results sent back to the channel.                                                            |
-| [Interactive web terminals](interactive_web_terminal/index.md)                                                            | Open an interactive web terminal to debug the running jobs.                                                                  |
-| [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.                                              |
+| 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/).            |
+| [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.                                         |
+| [Pipelines for merge requests](merge_request_pipelines/index.md)                                                          | Create pipelines specifically for merge requests.                                          |
+| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md)                                                                    | Use SSH keys in your build environment.                                                    |
+| [Triggering pipelines through the API](triggers/README.md)                                                                | Use the GitLab API to trigger a pipeline.                                                  |
+| [Pipeline schedules](../user/project/pipelines/schedules.md)                                                              | Trigger pipelines on a schedule.                                                           |
+| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md)                                          | Integrate one or more Kubernetes clusters to your project.                                 |
+| [ChatOps](chatops/README.md)                                                                                              | Trigger CI jobs from chat, with results sent back to the channel.                          |
+| [Interactive web terminals](interactive_web_terminal/index.md)                                                            | Open an interactive web terminal to debug the running jobs.                                |
+| [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. |
 
 ### GitLab Pages
 
diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 05d392d54cb..bcd6f6eb1cb 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -1,45 +1,65 @@
-# Introduction to environments and deployments
+# Environments and deployments
 
 > Introduced in GitLab 8.9.
 
-During the development of software, there can be many stages until it's ready
-for public consumption. You sure want to first test your code and then deploy it
-in a testing or staging environment before you release it to the public. That
-way you can prevent bugs not only in your software, but in the deployment
-process as well.
+Environments allow control of the continuous deployment of your software,
+all within GitLab.
 
-GitLab CI is capable of not only testing or building your projects, but also
+## Introduction
+
+There are many stages required in the software development process before the software is ready
+for public consumption.
+
+For example:
+
+1. Develop your code.
+1. Test your code.
+1. Deploy your code into a testing or staging environment before you release it to the public.
+
+This helps prevent bugs not only in your software, but in the deployment process as well.
+
+GitLab CI/CD is capable of not only testing or building your projects, but also
 deploying them in your infrastructure, with the added benefit of giving you a
 way to track your deployments. In other words, you can always know what is
 currently being deployed or has been deployed on your servers.
 
-## Overview
+It's important to know that:
 
-With environments, you can control the Continuous Deployment of your software
-all within GitLab. All you need to do is define them in your project's
-[`.gitlab-ci.yml`][yaml] as we will explore below. GitLab provides a full
-history of your deployments per every environment.
+- Environments are like tags for your CI jobs, describing where code gets deployed.
+- Deployments are created when [jobs](yaml/README.md#introduction) deploy versions of code to environments,
+  so every environment can have one or more deployments.
 
-Environments are like tags for your CI jobs, describing where code gets deployed.
-Deployments are created when [jobs](yaml/README.md#introduction) deploy versions of code to environments,
-so every environment can have one or more deployments. GitLab keeps track of
-your deployments, so you always know what is currently being deployed on your
-servers. If you have a deployment service such as [Kubernetes][kube]
+GitLab:
+
+- Provides a full history of your deployments per every environment.
+- Keeps track of your deployments, so you always know what is currently being deployed on your
+  servers.
+
+If you have a deployment service such as [Kubernetes](../user/project/clusters/index.md)
 enabled for your project, you can use it to assist with your deployments, and
 can even access a [web terminal](#web-terminals) for your environment from within GitLab!
 
-To better understand how environments and deployments work, let's consider an
-example. We assume that you have already created a project in GitLab and set up
-a Runner. The example will cover the following:
+## Configuring environments
+
+Configuring environments involves:
+
+1. Understanding how [pipelines](pipelines.md) work.
+1. Defining environments in your project's [`.gitlab-ci.yml`](yaml/README.md) file.
+
+The rest of this section illustrates how to configure environments and deployments using an example.
+It assumes you have already:
 
-- We are developing an application
-- We want to run tests and build our app on all branches
-- Our default branch is `master`
-- We deploy the app only when a pipeline on `master` branch is run
+- Created a [project](../gitlab-basics/create-project.md) in GitLab.
+- Set up [a Runner](runners/README.md).
 
-Let's see how it all ties together.
+In the scenario:
 
-## Defining environments
+- We are developing an application.
+- We want to run tests and build our app on all branches.
+- Our default branch is `master`.
+- We deploy the app only when a pipeline on `master` branch is run.
+
+### Defining environments
 
 Let's consider the following `.gitlab-ci.yml` example:
 
@@ -70,123 +90,64 @@ deploy_staging:
 
 We have defined 3 [stages](yaml/README.md#stages):
 
-- test
-- build
-- deploy
+- `test`
+- `build`
+- `deploy`
 
 The jobs assigned to these stages will run in this order. If a job fails, then
 the jobs that are assigned to the next stage won't run, rendering the pipeline
-as failed. In our case, the `test` job will run first, then the `build` and
-lastly the `deploy_staging`. With this, we ensure that first the tests pass,
-then our app is able to be built successfully, and lastly we deploy to the
-staging server.
+as failed.
+
+In our case:
+
+- The `test` job will run first.
+- Then the `build` job.
+- Lastly the `deploy_staging` job.
+
+With this configuration, we ensure that:
+
+- The tests pass.
+- Our app is able to be built successfully.
+- Lastly we deploy to the staging server.
 
+NOTE: **Note:**
 The `environment` keyword is just a hint for GitLab that this job actually
-deploys to this environment's `name`. It can also have a `url` which, as we
-will later see, is exposed in various places within GitLab. Each time a job that
-has an environment specified and succeeds, a deployment is recorded, remembering
+deploys to this environment's `name`. It can also have a `url` that is
+exposed in various places within GitLab. Each time a job that
+has an environment specified succeeds, a deployment is recorded, storing
 the Git SHA and environment name.
 
-> **Note:**
+In summary, with the above `.gitlab-ci.yml` we have achieved the following:
+
+- All branches will run the `test` and `build` jobs.
+- The `deploy_staging` job will run [only](yaml/README.md#onlyexcept-basic) on the `master`
+  branch, which means all merge requests that are created from branches don't
+  get deployed to the staging server.
+- When a merge request is merged, all jobs will run and the `deploy_staging`
+  job will deploy our code to a staging server while the deployment
+  will be recorded in an environment named `staging`.
+
 > Starting with GitLab 8.15, the environment name is exposed to the Runner in
 > two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is
 > the name given in `.gitlab-ci.yml` (with any variables expanded), while the
 > second is a "cleaned-up" version of the name, suitable for use in URLs, DNS,
 > etc.
->
-> **Note:**
+
 > Starting with GitLab 9.3, the environment URL is exposed to the Runner via
 > `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if
 > the URL was not defined there, the external URL from the environment would be
 > used.
 
-To sum up, with the above `.gitlab-ci.yml` we have achieved that:
-
-- All branches will run the `test` and `build` jobs.
-- The `deploy_staging` job will run [only](yaml/README.md#onlyexcept-basic) on the `master`
-  branch which means all merge requests that are created from branches don't
-  get to deploy to the staging server
-- When a merge request is merged, all jobs will run and the `deploy_staging`
-  in particular will deploy our code to a staging server while the deployment
-  will be recorded in an environment named `staging`.
-
-Let's now see how that information is exposed within GitLab.
+### Configuring manual deployments
 
-## Viewing the current status of an environment
+Converting automatically executed job into jobs requiring to a manual action involves
+adding `when: manual` to the job's configuration.
 
-The environment list under your project's **Operations > Environments**, is
-where you can find information of the last deployment status of an environment.
+To expand on the [previous example](#defining-environments), the following includes
+another job that deploys our app to a production server and is
+tracked by a `production` environment.
 
-Here's how the Environments page looks so far.
-
-![Environment view](img/environments_available.png)
-
-There's a bunch of information there, specifically you can see:
-
-- The environment's name with a link to its deployments
-- The last deployment ID number and who performed it
-- The job ID of the last deployment with its respective job name
-- The commit information of the last deployment such as who committed, to what
-  branch and the Git SHA of the commit
-- The exact time the last deployment was performed
-- A button that takes you to the URL that you have defined under the
-  `environment` keyword in `.gitlab-ci.yml`
-- A button that re-deploys the latest deployment, meaning it runs the job
-  defined by the environment name for that specific commit
-
-> **Notes:**
->
-> - While you can create environments manually in the web interface, we recommend
->   that you define your environments in `.gitlab-ci.yml` first. They will
->   be automatically created for you after the first deploy.
-> - The environments page can only be viewed by Reporters and above. For more
->   information on the permissions, see the [permissions documentation][permissions].
-> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured
->   will show up in the "Environment" and "Last deployment" lists.
-
-The information shown in the Environments page is limited to the latest
-deployments, but as you may have guessed an environment can have multiple
-deployments.
-
-## Viewing the deployment history of an environment
-
-GitLab keeps track of your deployments, so you always know what is currently
-being deployed on your servers. That way you can have the full history of your
-deployments per every environment right in your browser. Clicking on an
-environment will show the history of its deployments. Assuming you have deployed
-multiple times already, here's how a specific environment's page looks like.
-
-![Deployments](img/deployments_view.png)
-
-We can see the same information as when in the Environments page, but this time
-all deployments are shown. As you may have noticed, apart from the **Re-deploy**
-button there are now **Rollback** buttons for each deployment. Let's see how
-that works.
-
-## Rolling back changes
-
-You can't control everything, so sometimes things go wrong. When that unfortunate
-time comes GitLab has you covered. Simply by clicking the **Rollback** button
-that can be found in the deployments page
-(**Operations > Environments > `environment name`**) you can relaunch the
-job with the commit associated with it.
-
->**Note:**
-Bear in mind that your mileage will vary and it's entirely up to how you define
-the deployment process in the job's `script` whether the rollback succeeds or not.
-GitLab CI is just following orders.
-
-Thankfully that was the staging server that we had to rollback, and since we
-learn from our mistakes, we decided to not make the same again when we deploy
-to the production server. Enter manual actions for deployments.
-
-## Manually deploying to environments
-
-Turning a job from running automatically to a manual action is as simple as
-adding `when: manual` to it. To expand on our previous example, let's add
-another job that this time deploys our app to a production server and is
-tracked by a `production` environment. The `.gitlab-ci.yml` looks like this
-so far:
+The `.gitlab-ci.yml` file for this is as follows:
 
 ```yaml
 stages:
@@ -224,41 +185,62 @@ deploy_prod:
   - master
 ```
 
-The `when: manual` action exposes a play button in GitLab's UI and the
-`deploy_prod` job will only be triggered if and when we click that play button.
-You can find it in the pipeline, job, environment, and deployment views.
+The `when: manual` action:
+
+- Exposes a "play" button in GitLab's UI.
+- Means the `deploy_prod` job will only be triggered when the "play" button is clicked.
 
-| Pipelines | Single pipeline | Environments | Deployments | jobs |
-| --------- | ----------------| ------------ | ----------- | -------|
-| ![Pipelines manual action](img/environments_manual_action_pipelines.png) | ![Pipelines manual action](img/environments_manual_action_single_pipeline.png) | ![Environments manual action](img/environments_manual_action_environments.png) | ![Deployments manual action](img/environments_manual_action_deployments.png) | ![Builds manual action](img/environments_manual_action_jobs.png) |
+You can find the "play" button in the pipelines, environments, deployments, and jobs views.
 
-Clicking on the play button in either of these places will trigger the
-`deploy_prod` job, and the deployment will be recorded under a new
+| View            | Screenshot                                                                     |
+|:----------------|:-------------------------------------------------------------------------------|
+| Pipelines       | ![Pipelines manual action](img/environments_manual_action_pipelines.png)       |
+| Single pipeline | ![Pipelines manual action](img/environments_manual_action_single_pipeline.png) |
+| Environments    | ![Environments manual action](img/environments_manual_action_environments.png) |
+| Deployments     | ![Deployments manual action](img/environments_manual_action_deployments.png)   |
+| Jobs            | ![Builds manual action](img/environments_manual_action_jobs.png)               |
+
+Clicking on the play button in any view will trigger the `deploy_prod` job, and the deployment will be recorded under a new
 environment named `production`.
 
->**Note:**
-Remember that if your environment's name is `production` (all lowercase), then
+NOTE: **Note:**
+If your environment's name is `production` (all lowercase),
 it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).
-Double the benefit!
 
-## Dynamic environments
+### Configuring dynamic environments
 
-As the name suggests, it is possible to create environments on the fly by just
-declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments is
-the basis of [Review apps](review_apps/index.md).
+Other environments are good for deploying to stable environments like staging or production.
 
-NOTE: **Note:**
-The `name` and `url` parameters can use most of the CI/CD variables,
-including [predefined](variables/README.md#predefined-environment-variables),
-[project/group ones](variables/README.md#variables) and
-[`.gitlab-ci.yml` variables](yaml/README.md#variables). You however cannot use variables
-defined under `script` or on the Runner's side. There are also other variables that
-are unsupported in the context of `environment:name`. You can read more about
-[where variables can be used](variables/where_variables_can_be_used.md).
-
-GitLab Runner exposes various [environment variables][variables] when a job runs,
-and as such, you can use them as environment names. Let's add another job in
-our example which will deploy to all branches except `master`:
+However, what about environments for branches other than `master`? Dynamic environments can be used to achieve these.
+
+Dynamic environments make it possible to create environments on the fly by
+declaring their names dynamically in `.gitlab-ci.yml`.
+
+Dynamic environments form the basis of [Review apps](review_apps/index.md).
+
+#### Allowed variables
+
+The `name` and `url` parameters for dynamic environments can use most available CI/CD variables,
+including:
+
+- [Predefined environment variables](variables/README.md#predefined-environment-variables)
+- [Project and group variables](variables/README.md#variables)
+- [`.gitlab-ci.yml` variables](yaml/README.md#variables)
+
+However, you cannot use variables defined:
+
+- Under `script`.
+- On the Runner's side.
+
+There are also other variables that are unsupported in the context of `environment:name`.
+For more information, see [Where variables can be used](variables/where_variables_can_be_used.md).
+
+#### Example configuration
+
+GitLab Runner exposes various [environment variables](variables/README.md) when a job runs and so
+you can use them as environment names.
+
+In the following example, a job will deploy to all branches except `master`:
 
 ```yaml
 deploy_review:
@@ -274,39 +256,49 @@ deploy_review:
     - master
 ```
 
-Let's break it down in pieces. The job's name is `deploy_review` and it runs
-on the `deploy` stage. The `script` at this point is fictional, you'd have to
-use your own based on your deployment. Then, we set the `environment` with the
-`environment:name` being `review/$CI_COMMIT_REF_NAME`. Now that's an interesting
-one. Since the [environment name][env-name] can contain slashes (`/`), we can
-use this pattern to distinguish between dynamic environments and the regular
-ones.
-
-So, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`
-which takes the value of the branch name. Since `$CI_COMMIT_REF_NAME` itself may
-also contain `/`, or other characters that would be invalid in a domain name or
-URL, we use `$CI_ENVIRONMENT_SLUG` in the `environment:url` so that the
-environment can get a specific and distinct URL for each branch. In this case,
-given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something
-like `https://100-do-the-4f99a2.example.com`. Again, the way you set up
-the web server to serve these requests is based on your setup.
-
-You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`, e.g.:
-`https://$CI_COMMIT_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG`
-here because it is guaranteed to be unique, but if you're using a workflow like
-[GitLab Flow][gitlab-flow], collisions are very unlikely, and you may prefer
-environment names to be more closely based on the branch name - the example
-above would give you an URL like `https://100-do-the-thing.example.com`
-
-Last but not least, we tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches
-[`except`](yaml/README.md#onlyexcept-basic) master.
-
->**Note:**
+In this example:
+
+- The job's name is `deploy_review` and it runs on the `deploy` stage.
+- We set the `environment` with the `environment:name` as `review/$CI_COMMIT_REF_NAME`.
+  Since the [environment name](yaml/README.md#environmentname) can contain slashes (`/`), we can
+  use this pattern to distinguish between dynamic environments and the regular ones.
+- We tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches [`except`](yaml/README.md#onlyexcept-basic) `master`.
+
+For the value of:
+
+- `environment:name`, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`,
+  which takes the value of the branch name.
+- `environment:url`, since `$CI_COMMIT_REF_NAME` itself may also contain `/`, or other characters that
+  would be invalid in a domain name or URL, we use `$CI_ENVIRONMENT_SLUG` so that the environment can get a specific and distinct URL for each branch.
+
+  For example, given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something
+  like `https://100-do-the-4f99a2.example.com`. Again, the way you set up
+  the web server to serve these requests is based on your setup.
+
+  You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`. For example, `https://$CI_COMMIT_REF_SLUG.example.com`.
+  We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If you're using a workflow like
+  [GitLab Flow](../workflow/gitlab_flow.md), collisions are unlikely and you may prefer environment names to be more closely based on the branch name. The example
+  above would give you an URL like `https://100-do-the-thing.example.com`.
+
+NOTE: **Note:**
 You are not bound to use the same prefix or only slashes in the dynamic
-environments' names (`/`), but as we will see later, this will enable the
-[grouping similar environments](#grouping-similar-environments) feature.
+environments' names (`/`). However, this will enable the [grouping similar environments](#grouping-similar-environments) feature.
+
+### Complete example
+
+The configuration in this section provides a full development workflow where your app is:
+
+- Tested.
+- Built.
+- Deployed as a Review App.
+- Deployed to a staging server once the merge request is merged.
+- Finally, manually deployed to the production server.
 
-The whole `.gitlab-ci.yml` looks like this so far:
+The following combines the previous configuration examples, including:
+
+- Defining [simple environments](#defining-environments) for testing, building, and deployment to staging.
+- Adding [manual actions](#configuring-manual-deployments) for deployment to production.
+- Creating [dynamic environments](#configuring-dynamic-environments) for deployments for reviewing.
 
 ```yaml
 stages:
@@ -357,8 +349,9 @@ deploy_prod:
 ```
 
 A more realistic example would include copying files to a location where a
-webserver (NGINX) could then read and serve. The example below will copy the
-`public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
+webserver (for example, NGINX) could then read and serve.
+
+The example below will copy the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
 
 ```yaml
 review_app:
@@ -370,76 +363,157 @@ review_app:
     url: https://$CI_COMMIT_REF_SLUG.example.com
 ```
 
-It is assumed that the user has already set up NGINX and GitLab Runner in the
-server this job will run on.
+This example requires that NGINX and GitLab Runner are set up on the server this job will run on.
+
+NOTE: **Note:**
+See the [limitations](#limitations) section for some edge cases regarding naming of your branches and Review Apps.
+
+The complete example provides the following workflow for developers:
+
+- Create a branch locally.
+- Make changes and commit them
+- Push the branch to GitLab.
+- Create a merge request.
+
+Behind the scenes, GitLab runner will:
+
+- Pick up the changes and start running the jobs.
+- Run the jobs sequentially as defined in `stages`:
+  - First, run the tests.
+  - If the tests succeed, build the app.
+  - If the build succeeds, the app will be is deployed to an environment with a name specific to the
+    branch.
+
+So now, every branch:
+
+- Gets its own environment.
+- Is deployed to its own location, with the added benefit of:
+  - Having a [history of deployments](#viewing-deployment-history).
+  - Being able to [rollback changes](#retrying-and-rolling-back) if needed.
+
+For more information on using the URL, see [Using the environment URL](#using-the-environment-url).
+
+### Protected environments
+
+Environments can be "protected", restricting access to them.
+
+For more information, see [Protected environments](environments/protected_environments.md).
+
+## Working with environments
+
+Having configured environments, GitLab provides many features to work with them. These are documented below.
+
+### Viewing environments and deployments
+
+A list of environments and deployment statuses is available on project's **Operations > Environments** page.
+
+For example:
+
+![Environment view](img/environments_available.png)
+
+This example shows:
+
+- The environment's name with a link to its deployments.
+- The last deployment ID number and who performed it.
+- The job ID of the last deployment with its respective job name.
+- The commit information of the last deployment such as who committed, to what
+  branch, and the Git SHA of the commit.
+- The exact time the last deployment was performed.
+- A button that takes you to the URL that you have defined under the
+  `environment` keyword in `.gitlab-ci.yml`.
+- A button that re-deploys the latest deployment, meaning it runs the job
+  defined by the environment name for that specific commit.
+
+The information shown in the **Environments** page is limited to the latest
+deployments, but an environment can have multiple deployments.
+
+> **Notes:**
+>
+> - While you can create environments manually in the web interface, we recommend
+>   that you define your environments in `.gitlab-ci.yml` first. They will
+>   be automatically created for you after the first deploy.
+> - The environments page can only be viewed by Reporters and above. For more
+>   information on the permissions, see the [permissions documentation](../user/permissions.md).
+> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured
+>   will show up in the **Environment** and **Last deployment** lists.
+
+### Viewing deployment history
+
+GitLab keeps track of your deployments, so you:
+
+- Always know what is currently being deployed on your servers.
+- Can have the full history of your deployments per every environment.
 
->**Note:**
-Be sure to check out the [limitations](#limitations) section for some edge
-cases regarding naming of your branches and Review Apps.
+Clicking on an environment shows the history of its deployments. Here's an example **Environments** page
+with multiple deployments:
 
----
+![Deployments](img/deployments_view.png)
+
+This view is similar to the **Environments** page, but all deployments are shown. Also in this view
+is a **Rollback** button. For more information, see [Retrying and rolling back](#retrying-and-rolling-back).
 
-The development workflow would now be:
+### Retrying and rolling back
 
-- Developer creates a branch locally
-- Developer makes changes, commits and pushes the branch to GitLab
-- Developer creates a merge request
+If there is a problem with a deployment, you can retry it or roll it back.
 
-Behind the scenes:
+To retry or rollback a deployment:
 
-- GitLab Runner picks up the changes and starts running the jobs
-- The jobs run sequentially as defined in `stages`
-  - First, the tests pass
-  - Then, the job begins and successfully also passes
-  - Lastly, the app is deployed to an environment with a name specific to the
-    branch
+1. Navigate to **Operations > Environments**.
+1. Click on the environment.
+1. On the page that lists the deployment history for the environment, click the:
+   - **Rollback** button against a previously successful deployment, to roll back to that deployment.
+   - **Retry** button against the last deployment, to retry that deployment.
 
-So now, every branch gets its own environment and is deployed to its own place
-with the added benefit of having a [history of deployments](#viewing-the-deployment-history-of-an-environment)
-and also being able to [rollback changes](#rolling-back-changes) if needed.
-Let's briefly see where URL that's defined in the environments is exposed.
+NOTE: **Note:**
+The defined deployment process in the job's `script` determines whether the rollback succeeds or not.
 
-## Making use of the environment URL
+To avoid failed deployments being deployed in a production environment, [configure manual actions](#configing-manual-deployments) for production deployments.
+
+### Using the environment URL
 
 The [environment URL](yaml/README.md#environmenturl) is exposed in a few
 places within GitLab.
 
-| In a merge request widget as a link | In the Environments view as a button | In the Deployments view as a button |
-| -------------------- | ------------ | ----------- |
-| ![Environment URL in merge request](img/environments_mr_review_app.png) | ![Environment URL in environments](img/environments_available.png) | ![Environment URL in deployments](img/deployments_view.png) |
+These are:
+
+- In a merge request widget as a link:
+  ![Environment URL in merge request](img/environments_mr_review_app.png)
+- In the Environments view as a button:
+  ![Environment URL in environments](img/environments_available.png)
+- In the Deployments view as a button:
+  ![Environment URL in deployments](img/deployments_view.png)
 
-If a merge request is eventually merged to the default branch (in our case
-`master`) and that branch also deploys to an environment (in our case `staging`
-and/or `production`) you can see this information in the merge request itself.
+You can see this information in a merge request itself if:
+
+- The merge request is eventually merged to the default branch (usually `master`).
+- That branch also deploys to an environment (for example, `staging` or `production`).
+
+For example:
 
 ![Environment URLs in merge request](img/environments_link_url_mr.png)
 
-### Go directly from source files to public pages on the environment
+#### Going from source files to public pages
 
 With GitLab's [Route Maps](review_apps/index.md#route-maps) you can go directly
 from source files to public pages on the environment set for Review Apps.
 
-From then on, you have a full development cycle, where your app is tested, built, deployed
-as a Review App, deployed to a staging server once the merge request is merged,
-and finally manually deployed to the production server. This is a simple workflow,
-but when you have multiple developers working on a project
-at the same time, each of them pushing to their own branches, dynamic environments are
-created all the time. In which case, you probably want to do some clean up. Read
-next how environments can be stopped.
+### Stopping an environment
 
-## Stopping an environment
+Stopping an environment:
 
-By stopping an environment, you are effectively terminating its recording of the
-deployments that happen in it.
+- Removes it from the list of environments on the [**Environments** page](#viewing-environments-and-deployments).
+- Executes an [`on_stop` action](yaml/README.md#environmenton_stop), if defined.
 
-A branch is associated with an environment when the CI pipeline that is created
-for this branch, was recently deployed to this environment. You can think of
-the CI pipeline as the glue between the branch and the environment:
-`branch ➔ CI pipeline ➔ environment`.
+This is often used when multiple developers are working on a project at the same time,
+each of them pushing to their own branches, causing many dynamic environments to be created.
 
-There is a special case where environments can be manually stopped. That can
-happen if you provide another job for that matter. The syntax is a little
-tricky since a job calls another job to do the job.
+NOTE: **Note:**
+Starting with GitLab 8.14, dynamic environments will be stopped automatically
+when their associated branch is deleted.
+
+#### Automatically stopping an environment
+
+Environments can be stopped automatically using special configuration.
 
 Consider the following example where the `deploy_review` calls the `stop_review`
 to clean up and stop the environment:
@@ -470,35 +544,31 @@ stop_review:
     action: stop
 ```
 
-Setting the [`GIT_STRATEGY`][git-strategy] to `none` is necessary on the
-`stop_review` job so that the [GitLab Runner] won't try to checkout the code
+Setting the [`GIT_STRATEGY`](yaml/README.md#git-strategy) to `none` is necessary on the
+`stop_review` job so that the [GitLab Runner](https://docs.gitlab.com/runner/) won't try to check out the code
 after the branch is deleted.
 
->**Note:**
-Starting with GitLab 8.14, dynamic environments will be stopped automatically
-when their associated branch is deleted.
-
 When you have an environment that has a stop action defined (typically when
-the environment describes a review app), GitLab will automatically trigger a
+the environment describes a Review App), GitLab will automatically trigger a
 stop action when the associated branch is deleted. The `stop_review` job must
 be in the same `stage` as the `deploy_review` one in order for the environment
 to automatically stop.
 
-You can read more in the [`.gitlab-ci.yml` reference][onstop].
+You can read more in the [`.gitlab-ci.yml` reference](yaml/README.md#environmenton_stop).
 
-## Grouping similar environments
+### Grouping similar environments
 
-> [Introduced][ce-7015] in GitLab 8.14.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015) in GitLab 8.14.
 
-As we've seen in the [dynamic environments](#dynamic-environments), you can
-prepend their name with a word, then followed by a `/` and finally the branch
-name which is automatically defined by the `CI_COMMIT_REF_NAME` variable.
+As documented in [Configuring dynamic environments](#configuring-dynamic-environments), you can
+prepend environment name with a word, followed by a `/`, and finally the branch
+name, which is automatically defined by the `CI_COMMIT_REF_NAME` variable.
 
 In short, environments that are named like `type/foo` are presented under a
 group named `type`.
 
-In our minimal example, we name the environments `review/$CI_COMMIT_REF_NAME`
-where `$CI_COMMIT_REF_NAME` is the branch name:
+In our [minimal example](#example-configuration), we named the environments `review/$CI_COMMIT_REF_NAME`
+where `$CI_COMMIT_REF_NAME` is the branch name. Here is a snippet of the example:
 
 ```yaml
 deploy_review:
@@ -509,49 +579,47 @@ deploy_review:
     name: review/$CI_COMMIT_REF_NAME
 ```
 
-In that case, if you visit the Environments page, and provided the branches
+In this case, if you visit the **Environments** page and the branches
 exist, you should see something like:
 
 ![Environment groups](img/environments_dynamic_groups.png)
 
-## Monitoring environments
+### Monitoring environments
 
 > **Notes:**
 >
 > - For the monitoring dashboard to appear, you need to:
->   - Have enabled the [Prometheus integration][prom]
->   - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md)
-> - With GitLab 9.2, all deployments to an environment are shown directly on the
->  monitoring dashboard
+>   - Enable the [Prometheus integration](../user/project/integrations/prometheus.md).
+>   - Configure Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md)
+> - With GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
 
-If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment.
+If you have enabled [Prometheus for monitoring system and response metrics](../user/project/integrations/prometheus.md), you can monitor the performance behavior of your app running in each environment.
 
-Once configured, GitLab will attempt to retrieve [supported performance metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/index.html) for any
-environment which has had a successful deployment. If monitoring data was
-successfully retrieved, a Monitoring button will appear for each environment.
+Once configured, GitLab will attempt to retrieve [supported performance metrics](../user/project/integrations/prometheus_library/index.md) for any
+environment that has had a successful deployment. If monitoring data was
+successfully retrieved, a **Monitoring** button will appear for each environment.
 
 ![Environment Detail with Metrics](img/deployments_view.png)
 
-Clicking on the Monitoring button will display a new page, showing up to the last
+Clicking on the **Monitoring** button will display a new page showing up to the last
 8 hours of performance data. It may take a minute or two for data to appear
 after initial deployment.
 
-All deployments to an environment are shown directly on the monitoring dashboard
+All deployments to an environment are shown directly on the monitoring dashboard,
 which allows easy correlation between any changes in performance and a new
 version of the app, all without leaving GitLab.
 
 ![Monitoring dashboard](img/environments_monitoring.png)
 
-## Web terminals
+### Web terminals
+
+> Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners.
 
->**Note:**
-Web terminals were added in GitLab 8.15 and are only available to project
-maintainers and owners.
+If you deploy to your environments with the help of a deployment service (for example,
+the [Kubernetes integration](../user/project/clusters/index.md)), GitLab can open
+a terminal session to your environment.
 
-If you deploy to your environments with the help of a deployment service (e.g.,
-the [Kubernetes integration][kube]), GitLab can open
-a terminal session to your environment! This is a very powerful feature that
-allows you to debug issues without leaving the comfort of your web browser. To
+This is a powerful feature that allows you to debug issues without leaving the comfort of your web browser. To
 enable it, just follow the instructions given in the service integration
 documentation.
 
@@ -568,41 +636,71 @@ establish the terminal session:
 
 ![Terminal page](img/environments_terminal_page.png)
 
-This works just like any other terminal - you'll be in the container created
-by your deployment, so you can run shell commands and get responses in real
-time, check the logs, try out configuration or code tweaks, etc. You can open
-multiple terminals to the same environment - they each get their own shell
-session -  and even a multiplexer like `screen` or `tmux`!
+This works just like any other terminal. You'll be in the container created
+by your deployment so you can:
 
->**Note:**
-Container-based deployments often lack basic tools (like an editor), and may
-be stopped or restarted at any time. If this happens, you will lose all your
-changes! Treat this as a debugging tool, not a comprehensive online IDE.
+- Run shell commands and get responses in real time.
+- Check the logs.
+- Try out configuration or code tweaks etc.
 
----
+You can open multiple terminals to the same environment, they each get their own shell
+session and even a multiplexer like `screen` or `tmux`.
 
-While this is fine for deploying to some stable environments like staging or
-production, what happens for branches? So far we haven't defined anything
-regarding deployments for branches other than `master`. Dynamic environments
-will help us achieve that.
+NOTE: **Note:**
+Container-based deployments often lack basic tools (like an editor), and may
+be stopped or restarted at any time. If this happens, you will lose all your
+changes. Treat this as a debugging tool, not a comprehensive online IDE.
 
-## Checkout deployments locally
+### Check out deployments locally
 
-Since 8.13, a reference in the git repository is saved for each deployment, so
+Since GitLab 8.13, a reference in the Git repository is saved for each deployment, so
 knowing the state of your current environments is only a `git fetch` away.
 
-In your git config, append the `[remote "<your-remote>"]` block with an extra
+In your Git configuration, append the `[remote "<your-remote>"]` block with an extra
 fetch line:
 
-```
+```text
 fetch = +refs/environments/*:refs/remotes/origin/environments/*
 ```
 
+### Scoping environments with specs **[PREMIUM]**
+
+Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can behave differently for each
+environment. For example, you can [create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-variables-premium).
+
+In most cases, these features use the _environment specs_ mechanism, which offers
+an efficient way to implement scoping within each environment group.
+
+Let's say there are four environments:
+
+- `production`
+- `staging`
+- `review/feature-1`
+- `review/feature-2`
+
+Each environment can be matched with the following environment spec:
+
+| Environment Spec | `production` | `staging` | `review/feature-1` | `review/feature-2` |
+|:-----------------|:-------------|:----------|:-------------------|:-------------------|
+| *                | Matched      | Matched   | Matched            | Matched            |
+| production       | Matched      |           |                    |                    |
+| staging          |              | Matched   |                    |                    |
+| review/*         |              |           | Matched            | Matched            |
+| review/feature-1 |              |           | Matched            |                    |
+
+As you can see, you can use specific matching for selecting a particular environment,
+and also use wildcard matching (`*`) for selecting a particular environment group,
+such as [Review apps](review_apps/index.md) (`review/*`).
+
+NOTE: **Note:**
+The most _specific_ spec takes precedence over the other wildcard matching.
+In this case, `review/feature-1` spec takes precedence over `review/*` and `*` specs.
+
 ## Limitations
 
-1. You are limited to use only the [CI predefined variables][variables] in the
-   `environment: name`. If you try to re-use variables defined inside `script`
-   as part of the environment name, it will not work.
+You are limited to use only the [CI predefined variables](variables/README.md) in the
+`environment: name`. If you try to re-use variables defined inside `script`
+as part of the environment name, it will not work.
 
 ## Further reading
 
@@ -611,18 +709,3 @@ Below are some links you may find interesting:
 - [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment)
 - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
 - [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md)
-
-[Pipelines]: pipelines.md
-[yaml]: yaml/README.md
-[environments]: #environments
-[deployments]: #deployments
-[permissions]: ../user/permissions.md
-[variables]: variables/README.md
-[env-name]: yaml/README.md#environmentname
-[onstop]: yaml/README.md#environmenton_stop
-[ce-7015]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015
-[gitlab-flow]: ../workflow/gitlab_flow.md
-[gitlab runner]: https://docs.gitlab.com/runner/
-[git-strategy]: yaml/README.md#git-strategy
-[kube]: ../user/project/clusters/index.md
-[prom]: ../user/project/integrations/prometheus.md
diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md
new file mode 100644
index 00000000000..219af4ced9d
--- /dev/null
+++ b/doc/ci/environments/protected_environments.md
@@ -0,0 +1,48 @@
+# 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.