Commit f368832a authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'docs-stop-job' into 'master'

Explain problems from `stop: action` job in later stage

See merge request gitlab-org/gitlab!56627
parents 7ed9d3a8 796c2d71
...@@ -377,13 +377,7 @@ deleted. ...@@ -377,13 +377,7 @@ deleted.
You can configure environments to stop when a branch is 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 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 to clean up and stop the environment.
`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.
```yaml ```yaml
deploy_review: deploy_review:
...@@ -409,6 +403,14 @@ stop_review: ...@@ -409,6 +403,14 @@ stop_review:
when: manual 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), 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 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 `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. ...@@ -739,14 +741,68 @@ the `review/feature-1` spec takes precedence over `review/*` and `*` specs.
environment's operational health. **(PREMIUM)** environment's operational health. **(PREMIUM)**
- [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment): Secure your deployments. - [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment): Secure your deployments.
<!-- ## Troubleshooting ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues ### The job with `action: stop` doesn't run
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. In some cases, environments do not [stop when a branch is deleted](#stop-an-environment-when-a-branch-is-deleted).
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask. 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`
Each scenario can be a third-level heading, e.g. `### Getting error message X`. for the environment is also in a later stage, it can't start and the environment isn't deleted.
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. --> 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
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment