Commit 38f04ab4 authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'docs-yaml-when-keyword-update' into 'master'

Improve the when documentation

See merge request gitlab-org/gitlab!68254
parents be79657f b24f478b
...@@ -168,7 +168,7 @@ for a single run of the manual job. ...@@ -168,7 +168,7 @@ for a single run of the manual job.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4.
When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/index.md#whendelayed) keyword to When you do not want to run a job immediately, you can use the [`when:delayed`](../jobs/job_control.md#run-a-job-after-a-delay) keyword to
delay a job's execution for a certain period. delay a job's execution for a certain period.
This is especially useful for timed incremental rollout where new code is rolled out gradually. This is especially useful for timed incremental rollout where new code is rolled out gradually.
......
...@@ -497,6 +497,120 @@ test: ...@@ -497,6 +497,120 @@ test:
- "README.md" - "README.md"
``` ```
## Create a job that must be run manually
You can require that a job doesn't run unless a user starts it. This is called a **manual job**.
You might want to use a manual job for something like deploying to production.
To specify a job as manual, add [`when: manual`](../yaml/index.md#when) to the job
in the `.gitlab-ci.yml` file.
By default, manual jobs display as skipped when the pipeline starts.
You can use [protected branches](../../user/project/protected_branches.md) to more strictly
[protect manual deployments](#protect-manual-jobs) from being run by unauthorized users.
### Types of manual jobs
Manual jobs can be either optional or blocking:
- **Optional**: The default setting for manual jobs.
- They have [`allow_failure: true`](../yaml/index.md#allow_failure) by default.
- The status does not contribute to the overall pipeline status. A pipeline can
succeed even if all of its manual jobs fail.
- **Blocking**: An optional setting for manual jobs.
- Add `allow_failure: false` to the job configuration.
- The pipeline stops at the stage where the job is defined. To let the pipeline
continue running, [run the manual job](#run-a-manual-job).
- Merge requests in projects with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
enabled can't be merged with a blocked pipeline. Blocked pipelines show a status
of **blocked**.
### Run a manual job
To run a manual job, you must have permission to merge to the assigned branch.
To run a manual job:
1. Go to the pipeline, job, [environment](../environments/index.md#configure-manual-deployments),
or deployment view.
1. Next to the manual job, select **Play** (**{play}**).
### Protect manual jobs **(PREMIUM)**
Use [protected environments](../environments/protected_environments.md)
to define a list of users authorized to run a manual job. You can authorize only
the users associated with a protected environment to trigger manual jobs, which can:
- More precisely limit who can deploy to an environment.
- Block a pipeline until an approved user "approves" it.
To protect a manual job:
1. Add an `environment` to the job. For example:
```yaml
deploy_prod:
stage: deploy
script:
- echo "Deploy to production server"
environment:
name: production
url: https://example.com
when: manual
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
select the environment (`production` in this example) and add the users, roles or groups
that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
this list can trigger this manual job, as well as GitLab administrators
who are always able to use protected environments.
You can use protected environments with blocking manual jobs to have a list of users
allowed to approve later pipeline stages. Add `allow_failure: false` to the protected
manual job and the pipeline's next stages only run after the manual job is triggered
by authorized users.
## Run a job after a delay
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4.
Use [`when: delayed`](../yaml/index.md#when) to execute scripts after a waiting period, or if you want to avoid
jobs immediately entering the `pending` state.
You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time in seconds, unless a unit is
provided. `start_in` must be less than or equal to one week. Examples of valid values include:
- `'5'` (a value with no unit must be surrounded by single quotes)
- `5 seconds`
- `30 minutes`
- `1 day`
- `1 week`
When a stage includes a delayed job, the pipeline doesn't progress until the delayed job finishes.
You can use this keyword to insert delays between different stages.
The timer of a delayed job starts immediately after the previous stage completes.
Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passes.
The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes:
```yaml
timed rollout 10%:
stage: deploy
script: echo 'Rolling out 10% ...'
when: delayed
start_in: 30 minutes
```
To stop the active timer of a delayed job, click the **{time-out}** (**Unschedule**) button.
This job can no longer be scheduled to run automatically. You can, however, execute the job manually.
To start a delayed job immediately, select **Play** (**{play}**).
Soon GitLab Runner starts the job.
## Use predefined CI/CD variables to run jobs only in specific pipeline types ## Use predefined CI/CD variables to run jobs only in specific pipeline types
You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose
......
...@@ -188,7 +188,7 @@ release-branch-workflow: ...@@ -188,7 +188,7 @@ release-branch-workflow:
- testing - testing
``` ```
Example of the same workflow using [`when: manual`](../yaml/index.md#whenmanual) in GitLab CI/CD: Example of the same workflow using [`when: manual`](../jobs/job_control.md#create-a-job-that-must-be-run-manually) in GitLab CI/CD:
```yaml ```yaml
deploy_prod: deploy_prod:
......
...@@ -108,8 +108,8 @@ There are some high level differences between the products worth mentioning: ...@@ -108,8 +108,8 @@ There are some high level differences between the products worth mentioning:
- The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but - The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but
is in the YAML format (see [complete reference](../yaml/index.md)) instead of a Groovy DSL. It's most is in the YAML format (see [complete reference](../yaml/index.md)) instead of a Groovy DSL. It's most
analogous to the declarative Jenkinsfile format. analogous to the declarative Jenkinsfile format.
- Manual approvals or gates can be set up as [`when:manual` jobs](../yaml/index.md#whenmanual). These can - Manual approvals or gates can be set up as [`when:manual` jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually). These can
also leverage [`protected environments`](../yaml/index.md#protecting-manual-jobs) also leverage [`protected environments`](../jobs/job_control.md#run-a-job-after-a-delay)
to control who is able to approve them. to control who is able to approve them.
- GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using
container images to set up your build environment. For example, set up one pipeline that builds your build environment container images to set up your build environment. For example, set up one pipeline that builds your build environment
......
...@@ -206,7 +206,7 @@ For each `var` or `file_var`, a key and value are required. ...@@ -206,7 +206,7 @@ For each `var` or `file_var`, a key and value are required.
### Add manual interaction to your pipeline ### Add manual interaction to your pipeline
Manual actions, configured using the [`when:manual`](../yaml/index.md#whenmanual) keyword, [Manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually),
allow you to require manual interaction before moving forward in the pipeline. allow you to require manual interaction before moving forward in the pipeline.
You can do this straight from the pipeline graph. Just click the play button You can do this straight from the pipeline graph. Just click the play button
......
...@@ -1887,8 +1887,8 @@ variables: ...@@ -1887,8 +1887,8 @@ variables:
### `allow_failure` ### `allow_failure`
Use `allow_failure` when you want to let a job fail without impacting the rest of the CI Use `allow_failure` when you want to let a job fail without impacting the rest of the CI
suite. The default value is `false`, except for [manual](#whenmanual) jobs that use suite. The default value is `false`, except for [manual](../jobs/job_control.md#create-a-job-that-must-be-run-manually) jobs that use
the `when: manual` syntax. the [`when: manual`](#when) syntax.
In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`, In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`,
*including* `when: manual` jobs. *including* `when: manual` jobs.
...@@ -1952,28 +1952,23 @@ test_job_2: ...@@ -1952,28 +1952,23 @@ test_job_2:
### `when` ### `when`
Use `when` to implement jobs that run in case of failure or despite the Use `when` to configure the conditions for when jobs run. If not defined in a job,
failure. the default value is `when: on_success`.
The valid values of `when` are: **Keyword type**: Job keyword. You can use it only as part of a job.
1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed, **Possible inputs**:
or are considered successful because they have `allow_failure: true`.
1. `on_failure` - Execute job only when at least one job in an earlier stage fails.
1. `always` - Execute job regardless of the status of jobs in earlier stages.
1. `manual` - Execute job [manually](#whenmanual).
1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration.
Added in GitLab 11.14.
1. `never`:
- With job [`rules`](#rules), don't execute job.
- With [`workflow:rules`](#workflow), don't run pipeline.
In the following example, the script: - `on_success` (default): Run the job only when all jobs in earlier stages succeed
or have `allow_failure: true`.
- `manual`: Run the job only when [triggered manually](../jobs/job_control.md#create-a-job-that-must-be-run-manually).
- `always`: Run the job regardless of the status of jobs in earlier stages.
- `on_failure`: Run the job only when at least one job in an earlier stage fails.
- `delayed`: [Delay the execution of a job](../jobs/job_control.md#run-a-job-after-a-delay)
for a specified duration.
- `never`: Don't run the job.
1. Executes `cleanup_build_job` only when `build_job` fails. **Example of `when`**:
1. Always executes `cleanup_job` as the last step in pipeline regardless of
success or failure.
1. Executes `deploy_job` when you run it manually in the GitLab UI.
```yaml ```yaml
stages: stages:
...@@ -2012,116 +2007,26 @@ cleanup_job: ...@@ -2012,116 +2007,26 @@ cleanup_job:
when: always when: always
``` ```
#### `when:manual` In this example, the script:
A manual job is a type of job that is not executed automatically and must be explicitly
started by a user. You might want to use manual jobs for things like deploying to production.
To make a job manual, add `when: manual` to its configuration.
When the pipeline starts, manual jobs display as skipped and do not run automatically.
They can be started from the pipeline, job, [environment](../environments/index.md#configure-manual-deployments),
and deployment views.
Manual jobs can be either optional or blocking:
- **Optional**: Manual jobs have [`allow_failure: true](#allow_failure) set by default
and are considered optional. The status of an optional manual job does not contribute
to the overall pipeline status. A pipeline can succeed even if all its manual jobs fail.
- **Blocking**: To make a blocking manual job, add `allow_failure: false` to its configuration.
Blocking manual jobs stop further execution of the pipeline at the stage where the
job is defined. To let the pipeline continue running, click **{play}** (play) on
the blocking manual job.
Merge requests in projects with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) 1. Executes `cleanup_build_job` only when `build_job` fails.
enabled can't be merged with a blocked pipeline. Blocked pipelines show a status 1. Always executes `cleanup_job` as the last step in pipeline regardless of
of **blocked**. success or failure.
1. Executes `deploy_job` when you run it manually in the GitLab UI.
When you use [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs.
To trigger a manual job, a user must have permission to merge to the assigned branch.
You can use [protected branches](../../user/project/protected_branches.md) to more strictly
[protect manual deployments](#protecting-manual-jobs) from being run by unauthorized users.
In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you
can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and
earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
##### Protecting manual jobs **(PREMIUM)**
Use [protected environments](../environments/protected_environments.md)
to define a list of users authorized to run a manual job. You can authorize only
the users associated with a protected environment to trigger manual jobs, which can:
- More precisely limit who can deploy to an environment.
- Block a pipeline until an approved user "approves" it.
To protect a manual job:
1. Add an `environment` to the job. For example:
```yaml
deploy_prod:
stage: deploy
script:
- echo "Deploy to production server"
environment:
name: production
url: https://example.com
when: manual
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
select the environment (`production` in this example) and add the users, roles or groups
that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
this list can trigger this manual job, as well as GitLab administrators
who are always able to use protected environments.
You can use protected environments with blocking manual jobs to have a list of users
allowed to approve later pipeline stages. Add `allow_failure: false` to the protected
manual job and the pipeline's next stages only run after the manual job is triggered
by authorized users.
#### `when:delayed`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51352) in GitLab 11.4.
Use `when: delayed` to execute scripts after a waiting period, or if you want to avoid
jobs immediately entering the `pending` state.
You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time in seconds, unless a unit is
provided. `start_in` must be less than or equal to one week. Examples of valid values include:
- `'5'`
- `5 seconds`
- `30 minutes`
- `1 day`
- `1 week`
When a stage includes a delayed job, the pipeline doesn't progress until the delayed job finishes.
You can use this keyword to insert delays between different stages.
The timer of a delayed job starts immediately after the previous stage completes.
Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passes.
The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes: **Additional details**:
```yaml - In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you
timed rollout 10%: can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and
stage: deploy earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
script: echo 'Rolling out 10% ...' - The default behavior of `allow_failure` changes to `true` with `when: manual`.
when: delayed However, if you use `when: manual` with [`rules`](#rules), `allow_failure` defaults
start_in: 30 minutes to `false`.
```
To stop the active timer of a delayed job, click the **{time-out}** (**Unschedule**) button. **Related topics**:
This job can no longer be scheduled to run automatically. You can, however, execute the job manually.
To start a delayed job immediately, click the **Play** button. - `when` can be used with [`rules`](#rules) for more dynamic job control.
Soon GitLab Runner picks up and starts the job. - `when` can be used with [`workflow`](#workflow) to control when a pipeline can start.
### `environment` ### `environment`
...@@ -2249,7 +2154,7 @@ In the above example, the `review_app` job deploys to the `review` ...@@ -2249,7 +2154,7 @@ In the above example, the `review_app` job deploys to the `review`
environment. A new `stop_review_app` job is listed under `on_stop`. environment. A new `stop_review_app` job is listed under `on_stop`.
After the `review_app` job is finished, it triggers the After the `review_app` job is finished, it triggers the
`stop_review_app` job based on what is defined under `when`. In this case, `stop_review_app` job based on what is defined under `when`. In this case,
it is set to `manual`, so it needs a [manual action](#whenmanual) from it is set to `manual`, so it needs a [manual action](../jobs/job_control.md#create-a-job-that-must-be-run-manually) from
the GitLab UI to run. the GitLab UI to run.
Also in the example, `GIT_STRATEGY` is set to `none`. If the Also in the example, `GIT_STRATEGY` is set to `none`. If the
...@@ -3697,7 +3602,7 @@ view which job triggered a downstream pipeline. In the [pipeline graph](../pipel ...@@ -3697,7 +3602,7 @@ view which job triggered a downstream pipeline. In the [pipeline graph](../pipel
hover over the downstream pipeline job. hover over the downstream pipeline job.
In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you
can use [`when:manual`](#whenmanual) in the same job as `trigger`. In GitLab 13.4 and can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and
earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`.
You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086). You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086).
......
...@@ -79,7 +79,7 @@ case the runner downloads them using a dedicated API endpoint. ...@@ -79,7 +79,7 @@ case the runner downloads them using a dedicated API endpoint.
Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts
are reports (like JUnit, SAST, and DAST) which are parsed and rendered in the merge request. are reports (like JUnit, SAST, and DAST) which are parsed and rendered in the merge request.
Job status transitions are not all automated. A user may run [manual jobs](../../ci/yaml/index.md#whenmanual), cancel a pipeline, retry Job status transitions are not all automated. A user may run [manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually), cancel a pipeline, retry
specific failed jobs or the entire pipeline. Anything that specific failed jobs or the entire pipeline. Anything that
causes a job to change status triggers `ProcessPipelineService`, as it's responsible for causes a job to change status triggers `ProcessPipelineService`, as it's responsible for
tracking the status of the entire pipeline. tracking the status of the entire pipeline.
......
...@@ -469,7 +469,7 @@ If you want to know the in-depth details, here's what's really happening: ...@@ -469,7 +469,7 @@ If you want to know the in-depth details, here's what's really happening:
The following GitLab features are used among others: The following GitLab features are used among others:
- [Manual actions](../../ci/yaml/index.md#whenmanual) - [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually)
- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) - [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md)
- [Review Apps](../../ci/review_apps/index.md) - [Review Apps](../../ci/review_apps/index.md)
- [Artifacts](../../ci/yaml/index.md#artifacts) - [Artifacts](../../ci/yaml/index.md#artifacts)
......
...@@ -59,7 +59,7 @@ specific environment, there are a lot of use cases. To name a few: ...@@ -59,7 +59,7 @@ specific environment, there are a lot of use cases. To name a few:
- You want to promote what's running in staging, to production. You go to the - You want to promote what's running in staging, to production. You go to the
environments list, verify that what's running in staging is what you think is environments list, verify that what's running in staging is what you think is
running, then click on the [manual action](../../ci/yaml/index.md#whenmanual) to deploy to production. running, then click on the [manual job](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) to deploy to production.
- You trigger a deploy, and you have many containers to upgrade so you know - You trigger a deploy, and you have many containers to upgrade so you know
this takes a while (you've also throttled your deploy to only take down X this takes a while (you've also throttled your deploy to only take down X
containers at a time). But you need to tell someone when it's deployed, so you containers at a time). But you need to tell someone when it's deployed, so you
......
...@@ -119,7 +119,7 @@ For a software developer working in a team: ...@@ -119,7 +119,7 @@ For a software developer working in a team:
1. Pushes a commit with their final review. 1. Pushes a commit with their final review.
1. [Approves the merge request](approvals/index.md). 1. [Approves the merge request](approvals/index.md).
1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md).
1. Your changes get deployed to production with [manual actions](../../../ci/yaml/index.md#whenmanual) for GitLab CI/CD. 1. Your changes get deployed to production with [manual jobs](../../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) for GitLab CI/CD.
1. Your implementations were successfully shipped to your customer. 1. Your implementations were successfully shipped to your customer.
For a web developer writing a webpage for your company's website: For a web developer writing a webpage for your company's website:
......
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