[JENKINS-48523] Documentation for new when conditions tag and changeR…

…equest. Also adding documentation for changeset and changelog that was missing.
jenkins-infra · Mar 1, 2018 · ea97918 · ea97918
1 parent 2669cd8
commit ea97918
Showing 1 changed file with 30 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/syntax.adoc b/content/doc/book/pipeline/syntax.adoc
@@ -875,12 +875,42 @@ 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.).
+Without any parameters the stage would run as specified, for example: `when { changeRequest() }`
+but there are also a number of attributes to the change request that can be evaluated with the parameters:
+`id`, `target`, `branch`, `fork`, `url`, `title`, `author`, `authorDisplayName`, and `authorEmail` each corresponding to
+a `CHANGE_*` environment variable, for example: `when { changeRequest target: 'master' }`.
+The parameter `comparator` can be used to specify how the 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.
+For 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' }`
 
 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 parameter `comparator` can be used to specify how the 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' } }`