[JENKINS-44461] Add documentation for new when->beforeAgent field

jenkins-infra · Dec 20, 2017 · 09ee781 · 09ee781
1 parent 4cb63ac
commit 09ee781
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
@@ -767,6 +767,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 `stage`'s `agent`, if one is defined. However, this can
+be changed by specifying the `beforeAgent` option within the `when`
+block. If this is specified and is true, the `when` condition will be
+evaluated first, and the `agent` will only be entered if the `when`
+condition evaluated to true.
+
 [[when-example]]
 ===== Examples
 
@@ -907,6 +916,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