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.
|
