JENKINS-41118 - add customWorkspace docs

Also adding `node` `agent` type (which is just an alias for `label`, but hey) and the `reuseNode` option for `docker` and `dockerfile`, which we should have added earlier but forgot. Whoops.
jenkins-infra · Mar 16, 2017 · 5734440 · 5734440
1 parent 251cd98
commit 5734440
Showing 1 changed file with 27 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/syntax.adoc b/content/doc/book/pipeline/syntax.adoc
@@ -248,6 +248,18 @@ need to contain its own `agent` directive. For example: `agent none`
 label:: Execute the Pipeline, or stage, on an agent available in the Jenkins
 environment with the provided label. For example: `agent { label 'my-defined-label' }`
 
+node:: Execute the Pipeline, or stage, on an agent available in the Jenkins
+environment with the provided label, with additional options. For example:
+[source,groovy]
+----
+agent {
+    node {
+        label 'my-defined-label'
+        customWorkspace '/some/other/path'
+    }
+}
+----
+
 docker:: Execute the Pipeline, or stage, with the given container which will be
 dynamically provisioned on a <<../glossary#node, node>> pre-configured to
 accept Docker-based Pipelines, or on a node matching the optionally defined
@@ -271,6 +283,21 @@ dockerfile:: Execute the Pipeline, or stage, with a container built from a
 true }`. If building a `Dockerfile` in another directory, use the `dir`
 option: `agent { dockerfile { dir 'someSubDir' } }`.
 
+===== Additional Options
+
+These are a few options for two or more `agent` implementations. They are not
+required.
+
+customWorkspace:: A string. Run the Pipeline or individual `stage` this `agent`
+is applied to within this custom workspace, rather than the default. It can be
+either a relative path, in which case the custom workspace will be under the
+workspace root on the node, or an absolute path. This option is valid for
+`node`, `docker` and `dockerfile`.
+
+reuseNode:: A boolean, false by default. If true, run the container in the node
+specified at the top-level of the Pipeline, in the same workspace, rather than
+on a new node entirely. This option is valid for `docker` and `dockerfile`, and
+only has an effect when used on an `agent` for an individual `stage`.
 
 [[agent-example]]
 ===== Example