[JENKINS-48379, JENKINS-48380] Adding options and input for stage

jenkins-infra · Dec 19, 2017 · 9bb7d02 · 9bb7d02
1 parent bd829be
commit 9bb7d02
Showing 1 changed file with 109 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/syntax.adoc b/content/doc/book/pipeline/syntax.adoc
@@ -717,6 +717,115 @@ pipeline {
 <1> The tool name must be pre-configured in Jenkins under *Manage Jenkins* ->
 *Global Tool Configuration*.
 
+==== stage options
+
+The `options` directive for a `stage` is similar to the `options` directive at
+the root of the Pipeline. However, the `stage`-level `options` can only contain
+steps like `retry`, `timeout`, or `timestamps`, or Declarative options that are
+relevant to a `stage`, like `skipDefaultCheckout`.
+
+Steps in a `stage`'s `options` are invoked before entering the `stage`'s `agent`
+or checking any `when` conditions.
+
+===== Available Stage Options
+
+skipDefaultCheckout:: Skip checking out code from source control by default in
+the `agent` directive. For example: `options { skipDefaultCheckout() }`
+
+timeout:: Set a timeout period for the Pipeline run, after which Jenkins should
+abort the Pipeline. For example: `options { timeout(time: 1, unit: 'HOURS') }`
+
+retry:: On failure, retry the entire Pipeline the specified number of times.
+For example: `options { retry(3) }`
+
+timestamps:: Prepend all console output generated by the Pipeline run with the
+time at which the line was emitted. For example: `options { timestamps() }`
+
+[[stage-options-example]]
+===== Example
+
+[pipeline]
+----
+// Declarative //
+pipeline {
+    agent any
+    stages {
+        stage('Example') {
+            options {
+                timeout(time: 1, unit: 'HOURS') // <1>
+            }
+            steps {
+                echo 'Hello World'
+            }
+        }
+    }
+}
+// Script //
+----
+<1> Specifying a execution timeout of one hour for the `Example` stage, after
+which Jenkins will abort the Pipeline run.
+
+[NOTE]
+====
+A comprehensive list of available options is pending the completion of
+link:https://issues.jenkins-ci.org/browse/INFRA-1053[INFRA-1503].
+====
+
+==== input
+
+The `input` directive on a `stage` allows you to prompt for input, using the
+link:https://jenkins.io/doc/pipeline/steps/pipeline-input-step/#input-wait-for-interactive-input[`input` step].
+The `stage` will pause after any `options` have been applied, and before
+entering the `stage`s `agent` or evaluating its `when` condition. If the `input`
+is approved, the `stage` will then continue. Any parameters provided as part of
+the `input` submission will be available in the environment for the rest of the
+`stage`.
+
+===== Configuration options
+
+message:: Required. This will be presented to the user when they go to submit
+the `input`.
+
+id:: An optional identifier for this `input`. Defaults to the `stage` name.
+
+ok:: Optional text for the "ok" button on the `input` form.
+
+submitter:: An optional comma-separated list of users or external group names
+who are allowed to submit this `input`. Defaults to allowing any user.
+
+submitterParameter:: An optional name of an environment variable to set with
+the `submitter` name, if present.
+
+parameters:: An optional list of parameters to prompt the submitter to provide.
+See <<parameters>> for more information.
+
+[[input-example]]
+===== Example
+
+[pipeline]
+----
+// Declarative //
+pipeline {
+    agent any
+    stages {
+        stage('Example') {
+            input {
+                message "Should we continue?"
+                ok "Yes, we should."
+                submitter "alice,bob"
+                parameters {
+                    string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
+                }
+            }
+            steps {
+                echo "Hello, ${PERSON}, nice to meet you."
+            }
+        }
+    }
+}
+// Script //
+----
+
 ==== when
 
 The `when` directive allows the Pipeline to determine whether the stage should