Merge pull request #1430 from rsandell/JENKINS-48523

[JENKINS-48523] Documentation for new when conditions
jenkins-infra · Apr 6, 2018 · 7c7668e · 7c7668e
2 parents dce2fca + 7caf22f
commit 7c7668e
Showing 1 changed file with 43 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/syntax.adoc b/content/doc/book/pipeline/syntax.adoc
@@ -888,6 +888,37 @@ branch:: Execute the stage when the branch being built matches the branch
 pattern given, for example: `when { branch 'master' }`. Note that this only works on
 a multibranch Pipeline.
 
+buildingTag:: Execute the stage when the build is building a tag.
+Example: `when { buildingTag() }`
+
+changelog:: Execute the stage if the build's SCM changelog contains a given regular expression pattern,
+for example: `when { changelog '.*^\\[DEPENDENCY\\] .+$' }`
+
+changeset:: Execute the stage if the build's SCM changeset contains one or more files matching the given string or glob.
+Example: `when { changeset "**/*.js" }`
++
+By default the path matching will be case insensitive, this can be turned off with the `caseSensitive` parameter,
+for example: `when { changeset glob: "ReadMe.*", caseSensitive: true }`
+
+changeRequest:: Executes the stage if the current build is for a "change request"
+(a.k.a. Pull Request on GitHub and Bitbucket, Merge Request on GitLab or Change in Gerrit etc.).
+When no parameters are passed the stage runs on every change request, 
+for example: `when { changeRequest() }`. 
++
+By adding a filter attribute with parameter to the change request, 
+the stage can be made to run only on matching change requests.
+Possible attributes are 
+`id`, `target`, `branch`, `fork`, `url`, `title`, `author`, `authorDisplayName`, and `authorEmail`. 
+Each of these corresponds to
+a `CHANGE_*` environment variable, for example: `when { changeRequest target: 'master' }`.
++
+The optional parameter `comparator` may be added after an attribute 
+to specify how any patterns are evaluated for a match: 
+`EQUALS` for a simple string comparison (the default), 
+`GLOB` for an ANT style path glob (same as for example `changeset`), or
+`REGEXP` for regular expression matching.
+Example: `when { changeRequest authorEmail: "[\\w_-.]+@example.com", comparator: 'REGEXP' }`
+
 environment:: Execute the stage when the specified environment variable is set
 to the given value, for example: `when { environment name: 'DEPLOY_TO', value: 'production' }`
 
@@ -897,6 +928,18 @@ for example: `when { equals expected: 2, actual: currentBuild.number }`
 expression:: Execute the stage when the specified Groovy expression evaluates
 to true, for example: `when { expression { return params.DEBUG_BUILD } }`
 
+tag:: Execute the stage if the `TAG_NAME` variable matches the given pattern.
+Example: `when { tag "release-*" }`.
+If an empty pattern is provided the stage will execute if the `TAG_NAME` variable exists
+(same as `buildingTag()`).
++
+The optional parameter `comparator` may be added after an attribute 
+to specify how any patterns are evaluated for a match: 
+`EQUALS` for a simple string comparison, 
+`GLOB` (the default) for an ANT style path glob (same as for example `changeset`), or
+`REGEXP` for regular expression matching. 
+For example: `when { tag pattern: "release-\\d+", comparator: "REGEXP"}`
+
 not:: Execute the stage when the nested condition is false.
 Must contain one condition.
 For example: `when { not { branch 'master' } }`