Add note about auto-stopping of environments

2 files changed, 19 insertions, 5 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
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index bc9c0897f5a..1e096444903 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -627,7 +627,12 @@ deploy to production:
 
 #### environment:on_stop
 
-> [Introduced][ce-6669] in GitLab 8.13.
+>
+**Notes:**
+- [Introduced][ce-6669] in GitLab 8.13.
+- Starting with GitLab 8.14, when you have an environment that has a stop action
+  defined, GitLab will automatically trigger a stop action when the associated
+  branch is deleted.
 
 Closing (stoping) environments can be achieved with the `on_stop` keyword defined under
 `environment`. It declares a different job that runs in order to close