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

Improve the when documentation

See merge request gitlab-org/gitlab!68254

doc/ci/jobs/index.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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: