Skip to content

G
gitlab-ce
Commit 38f04ab4 authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

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

Improve the when documentation

See merge request gitlab-org/gitlab!68254
parents be79657f b24f478b
Show whitespace changes
Inline Side-by-side
Showing with 155 additions and 136 deletions
doc/ci/jobs/index.md
View file @ 38f04ab4
......@@ -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.
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.
This is especially useful for timed incremental rollout where new code is rolled out gradually.
......
doc/ci/jobs/job_control.md
View file @ 38f04ab4
......@@ -497,6 +497,120 @@ test:
- "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
You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose
......
doc/ci/migration/circleci.md
View file @ 38f04ab4
......@@ -188,7 +188,7 @@ release-branch-workflow:
- 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
deploy_prod:
......
doc/ci/migration/jenkins.md
View file @ 38f04ab4
......@@ -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
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.
- Manual approvals or gates can be set up as [`when:manual` jobs](../yaml/index.md#whenmanual). These can
also leverage [`protected environments`](../yaml/index.md#protecting-manual-jobs)
- 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`](../jobs/job_control.md#run-a-job-after-a-delay)
to control who is able to approve them.
- 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
......
doc/ci/pipelines/index.md
View file @ 38f04ab4
......@@ -206,7 +206,7 @@ For each `var` or `file_var`, a key and value are required.
### 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.
You can do this straight from the pipeline graph. Just click the play button
......
doc/ci/yaml/index.md
View file @ 38f04ab4
......@@ -1887,8 +1887,8 @@ variables:
### `allow_failure`
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
the `when: manual` syntax.
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`](#when) syntax.
In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`,
*including* `when: manual` jobs.
......@@ -1952,28 +1952,23 @@ test_job_2:
### `when`
Use `when` to implement jobs that run in case of failure or despite the
failure.
Use `when` to configure the conditions for when jobs run. If not defined in a job,
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,
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.
**Possible inputs**:
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.
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.
**Example of `when`**:
```yaml
stages:
......@@ -2012,116 +2007,26 @@ cleanup_job:
when: always
```
#### `when:manual`
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.
In this example, the script:
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**.
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.
1. Executes `cleanup_build_job` only when `build_job` fails.
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.
The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes:
**Additional details**:
```yaml
timed rollout 10%:
stage: deploy
script: echo 'Rolling out 10% ...'
when: delayed
start_in: 30 minutes
```
- 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`.
- The default behavior of `allow_failure` changes to `true` with `when: manual`.
However, if you use `when: manual` with [`rules`](#rules), `allow_failure` defaults
to `false`.
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.
**Related topics**:
To start a delayed job immediately, click the **Play** button.
Soon GitLab Runner picks up and starts the job.
- `when` can be used with [`rules`](#rules) for more dynamic job control.
- `when` can be used with [`workflow`](#workflow) to control when a pipeline can start.
### `environment`
......@@ -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`.
After the `review_app` job is finished, it triggers the
`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.
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
hover over the downstream pipeline job.
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`.
You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086).
......
doc/development/cicd/index.md
View file @ 38f04ab4
......@@ -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
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
causes a job to change status triggers `ProcessPipelineService`, as it's responsible for
tracking the status of the entire pipeline.
......
doc/development/documentation/index.md
View file @ 38f04ab4
......@@ -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:
- [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)
- [Review Apps](../../ci/review_apps/index.md)
- [Artifacts](../../ci/yaml/index.md#artifacts)
......
doc/user/project/deploy_boards.md
View file @ 38f04ab4
......@@ -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
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
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
......
doc/user/project/merge_requests/index.md
View file @ 38f04ab4
......@@ -119,7 +119,7 @@ For a software developer working in a team:
1. Pushes a commit with their final review.
1. [Approves the merge request](approvals/index.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.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7