Merge branch 'docs-environments-review' into 'master'

Docs: Environments Documentation review

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

doc/ci/environments.md

@@ -16,11 +16,11 @@ For example:
 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.
+This helps find bugs in your software, and also 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
+way to track your deployments. In other words, you will always know what is
 currently being deployed or has been deployed on your servers.
 
 It's important to know that:
@@ -31,12 +31,12 @@ It's important to know that:
 
 GitLab:
 
-- Provides a full history of your deployments per every environment.
+- Provides a full history of your deployments for each 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
+associated with 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!
 
 ## Configuring environments
@@ -46,8 +46,8 @@ 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:
+The rest of this section illustrates how to configure environments and deployments using
+an example scenario. It assumes you have already:
 
 - Created a [project](../gitlab-basics/create-project.md) in GitLab.
 - Set up [a Runner](runners/README.md).
@@ -94,9 +94,8 @@ We have defined 3 [stages](yaml/README.md#stages):
 - `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.
+The jobs assigned to these stages will run in this order. If any job fails, then
+the pipeline fails and jobs that are assigned to the next stage won't run.
 
 In our case:
 
@@ -104,15 +103,15 @@ In our case:
 - Then the `build` job.
 - Lastly the `deploy_staging` job.
 
-With this configuration, we ensure that:
+With this configuration, we:
 
-- The tests pass.
-- Our app is able to be built successfully.
+- Check that the tests pass.
+- Ensure that 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` that is
+deploys to the `name` environment. 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.
@@ -134,14 +133,13 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following:
 > etc.
 
 > 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.
+> `$CI_ENVIRONMENT_URL`. The URL is expanded from `.gitlab-ci.yml`, or if
+> the URL was not defined there, the external URL from the environment is used.
 
 ### Configuring manual deployments
 
-Converting automatically executed job into jobs requiring to a manual action involves
-adding `when: manual` to the job's configuration.
+Adding `when: manual` to an automatically executed job's configuration converts it to
+a job requiring manual action.
 
 To expand on the [previous example](#defining-environments), the following includes
 another job that deploys our app to a production server and is
@@ -187,7 +185,7 @@ deploy_prod:
 
 The `when: manual` action:
 
-- Exposes a "play" button in GitLab's UI.
+- Exposes a "play" button in GitLab's UI for that job.
 - Means the `deploy_prod` job will only be triggered when the "play" button is clicked.
 
 You can find the "play" button in the pipelines, environments, deployments, and jobs views.
@@ -200,8 +198,8 @@ You can find the "play" button in the pipelines, environments, deployments, and
 | 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`.
+Clicking on the play button in any view will trigger the `deploy_prod` job, and the
+deployment will be recorded as a new environment named `production`.
 
 NOTE: **Note:**
 If your environment's name is `production` (all lowercase),
@@ -209,14 +207,13 @@ it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).
 
 ### Configuring dynamic environments
 
-Other environments are good for deploying to stable environments like staging or production.
+Regular environments are good when deploying to "stable" environments like staging or production.
 
-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
+However, for environments for branches other than `master`, dynamic environments
+can be used. 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).
+Dynamic environments are a fundamental part of [Review apps](review_apps/index.md).
 
 #### Allowed variables
 
@@ -237,10 +234,10 @@ For more information, see [Where variables can be used](variables/where_variable
 
 #### Example configuration
 
-GitLab Runner exposes various [environment variables](variables/README.md) when a job runs and so
+GitLab Runner exposes various [environment variables](variables/README.md) when a job runs, so
 you can use them as environment names.
 
-In the following example, a job will deploy to all branches except `master`:
+In the following example, the job will deploy to all branches except `master`:
 
 ```yaml
 deploy_review:
@@ -261,28 +258,33 @@ 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`.
+  use this pattern to distinguish between dynamic and regular environments.
+- 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.
+  which receives the value of the branch name.
+- `environment:url`, we want a specific and distinct URL for each branch. `$CI_COMMIT_REF_NAME`
+  may contain a `/` or other characters that would be invalid in a domain name or URL,
+  so we use `$CI_ENVIRONMENT_SLUG` to get a "clean" or "safe" URL.
 
   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`.
+  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. In that case, you could use `$CI_COMMIT_REF_SLUG` in `environment:url` in
+  the example above: `https://$CI_COMMIT_REF_SLUG.example.com`, which would give a URL
+  of `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 (`/`). However, this will enable the [grouping similar environments](#grouping-similar-environments) feature.
+You are not required to use the same prefix or only slashes (`/`) in the dynamic environments'
+names. However, using this format will enable the [grouping similar environments](#grouping-similar-environments)
+feature.
 
 ### Complete example
 
@@ -292,7 +294,7 @@ The configuration in this section provides a full development workflow where you
 - Built.
 - Deployed as a Review App.
 - Deployed to a staging server once the merge request is merged.
-- Finally, manually deployed to the production server.
+- Finally, able to be manually deployed to the production server.
 
 The following combines the previous configuration examples, including:
 
@@ -348,8 +350,8 @@ deploy_prod:
   - master
 ```
 
-A more realistic example would include copying files to a location where a
-webserver (for example, NGINX) could then read and serve.
+A more realistic example would also include copying files to a location where a
+webserver (for example, NGINX) could then acess and serve them.
 
 The example below will copy the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
 
@@ -366,32 +368,33 @@ review_app:
 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.
+See the [limitations](#limitations) section for some edge cases regarding the naming of
+your branches and Review Apps.
 
-The complete example provides the following workflow for developers:
+The complete example provides the following workflow to developers:
 
 - Create a branch locally.
-- Make changes and commit them
+- Make changes and commit them.
 - Push the branch to GitLab.
 - Create a merge request.
 
-Behind the scenes, GitLab runner will:
+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
+  - If the build succeeds, the app 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:
+- Is deployed to its own unique 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).
+For more information, see [Using the environment URL](#using-the-environment-url).
 
 ### Protected environments
 
@@ -401,11 +404,12 @@ For more information, see [Protected environments](environments/protected_enviro
 
 ## Working with environments
 
-Having configured environments, GitLab provides many features to work with them. These are documented below.
+Once environments are configured, GitLab provides many features for working with them,
+as documented below.
 
 ### Viewing environments and deployments
 
-A list of environments and deployment statuses is available on project's **Operations > Environments** page.
+A list of environments and deployment statuses is available on each project's **Operations > Environments** page.
 
 For example:
 
@@ -416,11 +420,11 @@ 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
+- The commit information of the last deployment, such as who committed it, 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 takes you to the URL that you 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.
 
@@ -432,8 +436,8 @@ deployments, but an environment can have multiple deployments.
 > - 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).
+> - The environments page can only be viewed by users with [Reporter permission](../user/permissions.md#project-members-permissions)
+>   and above. For more information on 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.
 
@@ -442,7 +446,7 @@ deployments, but an environment can have multiple deployments.
 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.
+- Can have the full history of your deployments for every environment.
 
 Clicking on an environment shows the history of its deployments. Here's an example **Environments** page
 with multiple deployments:
@@ -460,9 +464,9 @@ To retry or rollback a deployment:
 
 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.
+1. In the deployment history list for the environment, click the:
+   - **Retry** button next to the last deployment, to retry that deployment.
+   - **Rollback** button next to a previously successful deployment, to roll back to that deployment.
 
 NOTE: **Note:**
 The defined deployment process in the job's `script` determines whether the rollback succeeds or not.
@@ -470,9 +474,7 @@ The defined deployment process in the job's `script` determines whether the roll
 ### Using the environment URL
 
 The [environment URL](yaml/README.md#environmenturl) is exposed in a few
-places within GitLab.
-
-These are:
+places within GitLab:
 
 - In a merge request widget as a link:
   ![Environment URL in merge request](img/environments_mr_review_app.png)
@@ -493,27 +495,28 @@ For example:
 #### 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 source files to public pages in the environment set for Review Apps.
 
 ### Stopping an environment
 
 Stopping an environment:
 
-- Moves it from the list of **Available** environments to the list of **Stopped** environments on the [**Environments** page](#viewing-environments-and-deployments).
+- Moves it from the list of **Available** environments to the list of **Stopped**
+  environments on the [**Environments** page](#viewing-environments-and-deployments).
 - Executes an [`on_stop` action](yaml/README.md#environmenton_stop), if defined.
 
 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.
 
 NOTE: **Note:**
-Starting with GitLab 8.14, dynamic environments will be stopped automatically
+Starting with GitLab 8.14, dynamic environments are 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`
+Consider the following example where the `deploy_review` job calls `stop_review`
 to clean up and stop the environment:
 
 ```yaml
@@ -542,14 +545,14 @@ stop_review:
     action: stop
 ```
 
-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.
+Setting the [`GIT_STRATEGY`](yaml/README.md#git-strategy) to `none` is necessary in 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.
 
 When you have an environment that has a stop action defined (typically when
 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
+be in the same `stage` as the `deploy_review` job in order for the environment
 to automatically stop.
 
 You can read more in the [`.gitlab-ci.yml` reference](yaml/README.md#environmenton_stop).
@@ -562,8 +565,8 @@ As documented in [Configuring dynamic environments](#configuring-dynamic-environ
 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 short, environments that are named like `type/foo` are all presented under the same
+group, named `type`.
 
 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:
@@ -588,13 +591,14 @@ exist, you should see something like:
 >
 > - For the monitoring dashboard to appear, you need to:
 >   - 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)
+>   - 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](../user/project/integrations/prometheus.md), 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 behavior of your app running in 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
+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)
@@ -604,8 +608,8 @@ Clicking on the **Monitoring** button will display a new page showing up to the
 after initial deployment.
 
 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.
+which allows easy correlation between any changes in performance and new
+versions of the app, all without leaving GitLab.
 
 ![Monitoring dashboard](img/environments_monitoring.png)
 
@@ -617,8 +621,8 @@ If you deploy to your environments with the help of a deployment service (for ex
 the [Kubernetes integration](../user/project/clusters/index.md)), GitLab can open
 a terminal session to your environment.
 
-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
+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.
 
 Once enabled, your environments will gain a "terminal" button:
@@ -663,8 +667,9 @@ 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](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-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](https://docs.gitlab.com/ee/ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium).
 
 In most cases, these features use the _environment specs_ mechanism, which offers
 an efficient way to implement scoping within each environment group.
@@ -696,9 +701,8 @@ In this case, `review/feature-1` spec takes precedence over `review/*` and `*` s
 
 ## Limitations
 
-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.
+In the `environment: name`, you are limited to only the [predefined environment variables](variables/predefined_variables.md).
+Re-using variables defined inside `script` as part of the environment name will not work.
 
 ## Further reading
 
@@ -707,3 +711,4 @@ 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)
+- [Deploy Boards for your applications running on Kubernetes](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]**

doc/ci/environments/protected_environments.md

@@ -9,8 +9,8 @@
 - 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.
+Since deploy jobs can be raised by different users with different roles, it is important that
+specific environments are "protected" to prevent unauthorized people from 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.
@@ -28,14 +28,14 @@ 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. In the **Allowed to Deploy** dropdown menu, select the role, users, or groups you
+   want to give deploy access to. Keep in mind that:
+   - 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 already associated with the project.
+   - Only users that have at least Developer permission level will appear in
+     the **Allowed to Deploy** dropdown menu.
 1. Click the **Protect** button.
 
 The protected environment will now appear in the list of protected environments.
@@ -44,5 +44,6 @@ The protected environment will now appear in the list of protected 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.
+- Update existing protected environments at any time by changing the access in the
+  **Allowed to Deploy** dropdown menu.
+- Unprotect a protected environment by clicking the **Unprotect** button for that environment.