1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
| Arguments may be given for each token in the form name="value" for strings and in the form name=value for booleans and numbers. In string arguments, escape ", \, and line terminators (\n or \r\n) with a \, e.g. arg1="\"quoted\""; arg2="c:\\path"; and arg3="one\ntwo". The brackets may be omitted if there are no arguments.
Examples: $TOKEN, ${TOKEN}, ${TOKEN, count=100}, ${ENV, var="PATH"}
Project Tokens ${DEFAULT_SUBJECT} This is the default email subject that is configured in Jenkinss system configuration page. ${DEFAULT_CONTENT} This is the default email content that is configured in Jenkinss system configuration page. ${DEFAULT_PRESEND_SCRIPT} This is the default pre-send script content that is configured in Jenkinss system configuration. This is the only token supported in the pre-send script entry field. ${DEFAULT_POSTSEND_SCRIPT} This is the default post-send script content that is configured in Jenkinss system configuration. This is the only token supported in the post-send script entry field. ${PROJECT_DEFAULT_SUBJECT} This is the default email subject for this project. The result of using this token in the advanced configuration is what is in the Default Subject field above. WARNING: Do not use this token in the Default Subject or Content fields. Doing this has an undefined result. ${PROJECT_DEFAULT_CONTENT} This is the default email content for this project. The result of using this token in the advanced configuration is what is in the Default Content field above. WARNING: Do not use this token in the Default Subject or Content fields. Doing this has an undefined result.
Extended Email Publisher Specific Tokens ${JELLY_SCRIPT,template="TEMPLATE_NAME"} Custom message content generated from a Jelly script template. There are two templates provided: "html" and "text". Custom Jelly templates should be placed in <tt>$JENKINS_HOME/email-templates</tt>. When using custom templates, the template filename without ".jelly" should be used for the "template" argument. You may also use the Config File Provider plugin to manage your templates. Prefix the managed file NAME with "managed:" for the template parameter. (Example: <tt>${JELLY_SCRIPT, template="managed:ManagedFileName"}</tt>) ${SCRIPT} Custom message content generated from a Groovy script. Custom scripts should be placed in <tt>$JENKINS_HOME/email-templates</tt>. When using a custom script the plugin will look in the resources forthe email-ext plugin first, and then in the <tt>$JENKINS_HOME/email-templates</tt>directory. No other directories will be searched. You may also use the Config File Provider plugin to manage your scripts. Prefix the managed file NAME with <tt>managed:</tt> for the template or script parameter. (Example: <tt>${SCRIPT, template="managed:ManagedFileName"}</tt>) script When this is used, only the last value in the script will be used in the expansion (script and template can not be used together). template The template in Groovy's SimpleTemplateEngine format. ${TEMPLATE} Custom message content generated from a template file. Custom templates should be placed in <tt>$JENKINS_HOME/email-templates</tt>. When using a custom script the plugin will look in the resources forthe email-ext plugin first, and then in the <tt>$JENKINS_HOME/email-templates</tt>directory. No other directories will be searched. You may also use the Config File Provider plugin to manage your templates. Use the "Custom File" config type for the template. Prefix the managed file NAME with "managed:" for the file parameter. (Example: <tt>${TEMPLATE, file="managed:ManagedFileName"}</tt>) file The template in plain text format.
Token Macro Plugin Tokens ${FAILED_TESTS} Displays failing unit test information, if any tests failed. showStack Shows stack trace in failing test output. Defaults to true. showMessage Shows error message in failing test output. Defaults to true. maxTests Display at most this many tests. No limit is set by default. onlyRegressions Display only the failing tests that are different from previous builds. Defaults to false. escapeHtml If set to true escapes characters in errors details and stack traces using HTML entities. Defaults to false.
${TEST_COUNTS,var="TYPE"} Displays the number of tests based on the type (var) passed in (total, pass, fail, skip). Defaults to total.
${GIT_BRANCH} Expands to the name of the branch that was built. Parameters all If specified, all the branches that point to the given commit is listed. By default, the token expands to just one of them. fullName If specified, this token expands to the full branch name, such as 'origin/master'. Otherwise, it only expands to the short name, such as 'master'.
${GIT_REVISION} Expands to the Git SHA1 commit ID that points to the commit that was built. Parameters length=N (optional, default to 40) Specify the commit ID length. Full SHA1 commit ID is 40 character long, but it is common to cut it off at 8 or 12 as that often provide enough uniqueness and is a lot more legible.
${ADMIN_EMAIL} Displays the email address for the Jenkins administrator
${BUILD_CAUSE} ${CAUSE} Displays the cause of the build.
${BUILD_LOG_EXCERPT} Displays an excerpt from the build log. start Regular expression to match the excerpt starting line (matching line is excluded). end Regular expression to match the excerpt ending line (matching line is excluded). See java.util.regex.Pattern
${BUILD_LOG} Displays the end of the build log. maxLines Display at most this many lines of the log. Defaults to 250. escapeHtml If true, HTML is escape. Defaults to false.
${BUILD_LOG_MULTILINE_REGEX} Displays build log segments that match the regular expression. regex java.util.regex.Pattern Segments of the build log that match this regular expression are included. See also null. No default. Required parameter maxMatches The maximum number of matches to include. If 0, all matches will be included. Defaults to 0. showTruncatedLines If true, include [...truncated ### lines...] lines. Defaults to true. substText If non-null, insert this text into the email rather than the entire segment. Defaults to null. escapeHtml If true, escape HTML. Defaults to false. matchedSegmentHtmlStyle If non-null, output HTML. Matched lines will become <b style="your-style-value">html escaped matched lines</b>. Defaults to null.
${BUILD_LOG_REGEX} Displays lines from the build log that match the regular expression. regex Lines that match this regular expression are included. See also java.util.regex.Pattern.Defaults to "(?i)\\b(error|exception|fatal|fail(ed|ure)|un(defined|resolved))\\b" linesBefore The number of lines to include before the matching line. Lines that overlap with another match or linesAfter are only inlcuded once. Defaults to 0. linesAfter The number of lines to include after the matching line. Lines that overlap with another match or linesBefore are only included once. Defaults to 0. maxMatches The maximum number of matches to include from the head of the log. If 0, all matches will be included. Defaults to 0. maxTailMatches The maximum number of matches to include from the tail of the log. When combined with maxMatches, it further limits the matches to the tail end of matched results. If 0, all matches will be included. Defaults to 0. showTruncatedLines If true, include [...truncated ### lines...] lines. Defaults to true. substText If non-null, insert this text into the email rather than the entire line. Defaults to null. escapeHtml If true, escape HTML. Defauts to false. matchedLineHtmlStyle If non-null, output HTML. Matched lines will become <b style="your-style-value"> html escaped matched line</b>. Defaults to null. addNewline If true, adds a newline after subsText. Defaults to true. defaultValue This value will be used if nothing is replaced. greedy When false and maxMatches is non-zero it causes more conservative addition of results when used with other parameters such as linesBefore and linesAfter
${BUILD_NUMBER} Expands to the current build number, a sequential auto-incrementing unique number that identifies the build, such as "125"
${BUILD_STATUS} Displays the status of the current build. (failing, success, etc...)
${BUILD_URL} Displays the URL for the current build
${CHANGES_SINCE_LAST_BUILD} ${CHANGES} Displays the changes since the last build. showDependencies If true, changes to projects this build depends on are shown. Defaults to false showPaths If true, the paths, modified by a commit are shown. Defaults to false format For each commit listed, a string containing %X, where %x is one of: %a author %d date %m message %p path %r revision Not all revision systems support %d and %r. If specified showPaths argument is ignored. Defaults to "[%a] %m\\n"
pathFormat A string containing %p to indicate how to print paths. Defaults to "\\t%p\\n" regex A regular expression. replace A replacement for all sub-strings of the change message that match the given regular expression. default Message to use when no changes are detected. Defaults to "No changes\n"
${CHANGES_SINCE_LAST_SUCCESS} Displays the changes since the last successful build. reverse If true, show most recent builds at the top instead of the bottom. Defaults to false. format For each build listed, a string containing %X, where %X is one of %c changes %n build number Defaults to Changes for Build #%n\n%c\n
changesFormat For each change in a build. See ${CHANGES_SINCE_LAST_BUILD} for placeholders. Following Parameters are also supported: showPaths, pathFormat, showDependencies, dateFormat, regex, replace, default. See ${CHANGES_SINCE_LAST_BUILD} details.
${CHANGES_SINCE_LAST_UNSTABLE} Expands to the changes since the last unstable or successful build. reverse If true, show most recent builds at the top instead of the bottom. Defaults to false. format For each build listed, a string containing %X, where %X is one of %c changes %n build number Defaults to Changes for Build #%n\n%c\n
changesFormat For each change in a build. See ${CHANGES_SINCE_LAST_BUILD} for placeholders. Following Parameters are also supported: showPaths, pathFormat, showDependencies, dateFormat, regex, replace, default. See ${CHANGES_SINCE_LAST_BUILD} details.
${ENV,var="VARIABLENAME"} Expands to an environment variable (specified here as VARIABLENAME) from the build environment. Note that this does not include any variables set by the build scripts themselves, only those set by Jenkins and other plugins.
${JENKINS_URL} Displays the URL to the Jenkins server. (You can change this on the system configuration page.)
${JOB_DESCRIPTION} Displays the description of the job.
${LOG_REGEX} Uses a regular expression to find a single log entry and generates a new output using the capture groups from it. This is partially based on the description-setter plugin (https://github.com/jenkinsci/description-setter-plugin).
${PROJECT_NAME} Displays the project's full name. (See AbstractProject.getFullDisplayName) ${PROJECT_DISPLAY_NAME} Displays the project's display name. (See AbstractProject.getDisplayName)
${PROJECT_URL} Displays a URL to the project's page.
${PROPFILE,file="FILENAME",property="PROPERTYNAME"} Expands to the value of a property in a property file. The filename is relative to the build workspace root.
${FILE,path="PATH"} Expands to the contents of a file. The file path is relative to the build workspace root.
${XML,file="FILE",xpath="XPATH"} Expands to the result(s) of an XPath expression run against the given XML file. If the XPath evaluates to more than one value, then a semicolon-separated string is returned. The file path is relative to the build workspace root.
In addition to the tokens, you can modify the result of the token expansion using parameter expansions. They follow similar rules as bash Parameter Expansions. The supported expansions are: ${#TOKEN} which resolves to the length of the expanded token value, ${TOKEN:offset:length} which takes a substring of the token result (length is optional and offset and length can both be negative), ${TOKEN#pattern} which matches the pattern against the start of the expanded token and removes it if it, ${TOKEN%pattern} which matches the pattern against the end of the expanded token and removes it it if matches.
|