Merge pull request #1288 from abayer/jenkins-48379-48380

[JENKINS-48379, JENKINS-48380] Adding options and input for stage
jenkins-infra · Jan 13, 2018 · ff40d07 · ff40d07
2 parents f93ba1c + b3a9f84
commit ff40d07
Showing 1 changed file with 106 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/syntax.adoc b/content/doc/book/pipeline/syntax.adoc
@@ -493,6 +493,9 @@ the `agent` directive. For example: `options { skipDefaultCheckout() }`
 
 skipStagesAfterUnstable:: Skip stages once the build status has gone to UNSTABLE. For example: `options { skipStagesAfterUnstable() }`
 
+checkoutToSubdirectory:: Perform the automatic source control checkout
+in a subdirectory of the workspace. For example: `options { checkoutToSubdirectory('foo') }`
+
 timeout:: Set a timeout period for the Pipeline run, after which Jenkins should
 abort the Pipeline. For example: `options { timeout(time: 1, unit: 'HOURS') }`
 
@@ -532,6 +535,54 @@ A comprehensive list of available options is pending the completion of
 link:https://issues.jenkins-ci.org/browse/INFRA-1053[INFRA-1503].
 ====
 
+===== 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`.
+
+Inside a `stage`, the steps in the `options` directive are invoked before
+entering the `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 this stage, after which Jenkins should
+abort the stage. For example: `options { timeout(time: 1, unit: 'HOURS') }`
+
+retry:: On failure, retry this stage the specified number of times.
+For example: `options { retry(3) }`
+
+timestamps:: Prepend all console output generated during this stage 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.
+
 ==== parameters
 
 The `parameters` directive provides a list of parameters which a user should
@@ -733,6 +784,61 @@ pipeline {
 <1> The tool name must be pre-configured in Jenkins under *Manage Jenkins* ->
 *Global Tool Configuration*.
 
+==== 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