Add note about auto-stopping of environments

1 files changed, 13 insertions, 4 deletions

diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 861a639b3fc..cc65f0ad8ad 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -395,11 +395,12 @@ next how environments can be stopped.
 By stopping an environment, you are effectively terminating its recording of the
 deployments that happen in it.
 
->**Note:**
-Starting with GitLab 8.14, dynamic environments will be stopped automatically
-when their associated branch is removed.
+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`.
 
-There is a special case where environments can be manually closed. That can
+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.
 
@@ -429,6 +430,14 @@ stop_review:
     action: stop
 ```
 
+>**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
+stop action when the associated branch is deleted.
+
 You can read more in the [`.gitlab-ci.yml` reference][onstop].
 
 ## Grouping similar environments