Documentation for delayed jobs

3 files changed, 49 insertions, 0 deletions

diff --git a/doc/ci/img/pipeline_incremental_rollout.png b/doc/ci/img/pipeline_incremental_rollout.png
new file mode 100644
index 00000000000..b3498e9a5a5
--- /dev/null
+++ b/doc/ci/img/pipeline_incremental_rollout.png
diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md
index ea47d676edb..44589500eb0 100644
--- a/doc/ci/pipelines.md
+++ b/doc/ci/pipelines.md
@@ -193,6 +193,18 @@ stage has a job with a manual action.
 
 ![Pipelines example](img/pipelines.png)
 
+### Delay a particular job in the pipeline graph
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4.
+
+When you do not want to run a job immediately, you can [delay the job to run after a certain period](yaml/README.md#delayed).
+This is especially useful for timed incremental rollout that new code is rolled out gradually.
+For example, if you start rolling out new code and users do not experience trouble, GitLab automatically completes the deployment from 0% to 100%. 
+Alternatively, if you start rolling out and you noticed that a few users experience trouble with the version,
+you can stop the timed incremental rollout by canceling the pipeline, and [rolling](environments.md#rolling-back-changes) it back to the stable version.
+
+![Pipelines example](img/pipeline_incremental_rollout.png)
+
 ### Ordering of jobs in pipeline graphs
 
 **Regular pipeline graph**
@@ -211,6 +223,7 @@ by name. The order of severity is:
 - pending
 - running
 - manual
+- scheduled
 - canceled
 - success
 - skipped
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 8b770495853..f0738252640 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -673,6 +673,42 @@ user wants to trigger an action. In other words, in order to trigger a manual
 action assigned to a branch that the pipeline is running for, user needs to
 have ability to merge to this branch.
 
+### `when:delayed`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4.
+
+Delayed job are for executing scripts after a certain period.
+This is useful if you want to avoid jobs entering `pending` state immediately.
+
+You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is
+provided. `start_key` must be less than or equal to one hour. Examples of valid values include:
+
+- `10 seconds`
+- `30 minutes`
+- `1 hour`
+
+When there is a delayed job in a stage, the pipeline will not progress until the delayed job has finished.
+This means this keyword can also be used for inserting delays between different stages.
+
+The timer of a delayed job starts immediately after the previous stage has completed.
+Similar to other types of jobs, a delayed job's timer will not start unless the previous stage passed.
+
+The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed:
+
+```yaml
+timed rollout 10%:
+  stage: deploy
+  script: echo 'Rolling out 10% ...'
+  when: delayed
+  start_in: 30 minutes
+```
+
+You can stop the active timer of a delayed job by clicking the **Unschedule** button.
+This job will never be executed in the future unless you execute the job manually.
+
+You can start a delayed job immediately by clicking the **Play** button.
+GitLab runner will pick your job soon and start the job.
+
 ## `environment`
 
 > **Notes:**