From cd42e9ad3a90756a4d2b28ec921b1ceb57579d4f Mon Sep 17 00:00:00 2001
From: Winnie Hellmann <winnie@gitlab.com>
Date: Thu, 11 Oct 2018 02:50:42 +0000
Subject: [PATCH] Documentation for delayed jobs

---
 doc/ci/img/pipeline_incremental_rollout.png | Bin 0 -> 4794 bytes
 doc/ci/pipelines.md                         |  13 +++++++
 doc/ci/yaml/README.md                       |  36 ++++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 doc/ci/img/pipeline_incremental_rollout.png

diff --git a/doc/ci/img/pipeline_incremental_rollout.png b/doc/ci/img/pipeline_incremental_rollout.png
new file mode 100644
index 0000000000000000000000000000000000000000..b3498e9a5a53d0a3852f5eabd004dc0ab37bdacd
GIT binary patch
literal 4794
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
D&lGvP

literal 0
HcmV?d00001

diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md
index ea47d676edbb4..44589500eb069 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 8b77049585389..f0738252640e8 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:**
-- 
GitLab