diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 3bba94f8b835c66ee5aec619ce6d2b36297f0fbd..3c31ba45d3d243f9d026832a62613efe74b7336b 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -535,6 +535,7 @@ deploy_review:
     - master
 
 stop_review:
+  stage: deploy
   variables:
     GIT_STRATEGY: none
   script:
@@ -555,7 +556,9 @@ 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.
+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].
 
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 63be61d1bca7f28df2564723fd4d2e909a2c19e7..a73598df81244b4484eafa8063d22d8f63a041b2 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -690,6 +690,8 @@ The `stop_review_app` job is **required** to have the following keywords defined
 - `when` - [reference](#when)
 - `environment:name`
 - `environment:action`
+- `stage` should be the same as the `review_app` in order for the environment
+  to stop automatically when the branch is deleted
 
 #### dynamic environments