1 files changed, 74 insertions, 18 deletions
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index abb12852fac..6da568f23e7 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -377,13 +377,7 @@ deleted.
 You can configure environments to stop when a branch is deleted.
 
 The following example shows a `deploy_review` job that calls a `stop_review` job
-to clean up and stop the environment. The `stop_review` job must be in the same
-`stage` as the `deploy_review` job.
-
-Both jobs must have the same [`rules`](../yaml/README.md#onlyexcept-basic)
-or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. Otherwise,
-the `stop_review` job might not be included in all pipelines that include the
-`deploy_review` job, and you cannot trigger `action: stop` to stop the environment automatically.
+to clean up and stop the environment.
 
 ```yaml
 deploy_review:
@@ -409,6 +403,14 @@ stop_review:
       when: manual
 ```
 
+Both jobs must have the same [`rules`](../yaml/README.md#onlyexcept-basic)
+or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. Otherwise,
+the `stop_review` job might not be included in all pipelines that include the
+`deploy_review` job, and you cannot trigger `action: stop` to stop the environment automatically.
+
+The job with [`action: stop` might not run](#the-job-with-action-stop-doesnt-run)
+if it's in a later stage than the job that started the environment.
+
 If you can't use [pipelines for merge requests](../merge_request_pipelines/index.md),
 set the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` in the
 `stop_review` job. Then the [runner](https://docs.gitlab.com/runner/) doesn't
@@ -739,14 +741,68 @@ the `review/feature-1` spec takes precedence over `review/*` and `*` specs.
   environment's operational health. **(PREMIUM)**
 - [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment): Secure your deployments.
 
-<!-- ## Troubleshooting
-
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
-
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+## Troubleshooting
+
+### The job with `action: stop` doesn't run
+
+In some cases, environments do not [stop when a branch is deleted](#stop-an-environment-when-a-branch-is-deleted).
+
+For example, the environment might start in a stage that also has a job that failed.
+Then the jobs in later stages job don't start. If the job with the `action: stop`
+for the environment is also in a later stage, it can't start and the environment isn't deleted.
+
+To ensure the `action: stop` can always run when needed, you can:
+
+- Put both jobs in the same stage:
+
+  ```yaml
+  stages:
+    - build
+    - test
+    - deploy
+
+  ...
+
+  deploy_review:
+    stage: deploy
+    environment:
+      name: review/$CI_COMMIT_REF_NAME
+      url: https://$CI_ENVIRONMENT_SLUG.example.com
+      on_stop: stop_review
+
+  stop_review:
+    stage: deploy
+    environment:
+      name: review/$CI_COMMIT_REF_NAME
+      action: stop
+    when: manual
+  ```
+
+- Add a [`needs`](../yaml/README.md#needs) entry to the `action: stop` job so the
+  job can start out of stage order:
+
+  ```yaml
+  stages:
+    - build
+    - test
+    - deploy
+    - cleanup
+
+  ...
+
+  deploy_review:
+    stage: deploy
+    environment:
+      name: review/$CI_COMMIT_REF_NAME
+      url: https://$CI_ENVIRONMENT_SLUG.example.com
+      on_stop: stop_review
+
+  stop_review:
+    stage: cleanup
+    needs:
+      - deploy_review
+    environment:
+      name: review/$CI_COMMIT_REF_NAME
+      action: stop
+    when: manual
+  ```