Merge pull request #1290 from abayer/jenkins-44461

[JENKINS-44461] Add documentation for new when->beforeAgent field
jenkins-infra · Jan 13, 2018 · 003b9ea · 003b9ea
2 parents ff40d07 + bb442af
commit 003b9ea
Showing 1 changed file with 37 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/syntax.adoc b/content/doc/book/pipeline/syntax.adoc
@@ -889,6 +889,15 @@ anyOf:: Execute the stage when at least one of the nested conditions is true.
 Must contain at least one condition.
 For example: `when { anyOf { branch 'master'; branch 'staging' } }`
 
+===== Evaluating `when` before entering the `stage`'s `agent`
+
+By default, the `when` condition for a `stage` will be evaluated after
+entering the `agent` for that `stage`, if one is defined. However, this can
+be changed by specifying the `beforeAgent` option within the `when`
+block. If `beforeAgent` is set to `true`, the `when` condition will be
+evaluated first, and the `agent` will only be entered if the `when`
+condition evaluates to true.
+
 [[when-example]]
 ===== Examples
 
@@ -1029,6 +1038,34 @@ pipeline {
 // Script //
 ----
 
+.`beforeAgent`
+[pipeline]
+----
+// Declarative //
+pipeline {
+    agent none
+    stages {
+        stage('Example Build') {
+            steps {
+                echo 'Hello World'
+            }
+        }
+        stage('Example Deploy') {
+            agent {
+                label "some-label"
+            }
+            when {
+                beforeAgent true
+                branch 'production'
+            }
+            steps {
+                echo 'Deploying'
+            }
+        }
+    }
+}
+// Script //
+----
 === Parallel
 
 Stages in Declarative Pipeline may declare a number of nested stages within