Groovy Postbuild Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID groovy-postbuild Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
2.2.2 (archives)
Oct 17, 2015
script-security (version:1.5)
Source Code
Issue Tracking
Pull Requests
Open Issues
Pull Requests
Stefan Wolf (id: wolfs)
Serban Iordache (id: beryx)
Usage Installations 2014-Nov 4206
2014-Dec 4258
2015-Jan 4422
2015-Feb 4634
2015-Mar 4912
2015-Apr 4962
2015-May 5063
2015-Jun 5386
2015-Jul 5630
2015-Aug 5689
2015-Sep 5837
2015-Oct 6078

This plugin executes a groovy script in the Jenkins JVM. Typically, the script checks some conditions and changes accordingly the build result, puts badges next to the build in the build history and/or displays information on the build summary page.

Migration from 1.X

From version 2.0, Groovy Postbuild plugin introduces Script Security Plugin.
Administrators can prevent users without proper privileges from running harmful scripts.
For details, see Script Security Plugin.
This doesn't affect Jenkins without security enabled and users with administrative privilege (to be exact, with RUN_SCRIPTS permission).

When you upgrade the Groovy Postbuild plugin from 1.X to 2.X, you and your Jenkins users
also requires update configurations of Groovy Postbuild, or they will fail with outputs like this:

ERROR: Failed to evaluate groovy script.
org.jenkinsci.plugins.scriptsecurity.scripts.UnapprovedUsageException: script not yet approved for use
	at org.jenkinsci.plugins.scriptsecurity.scripts.ScriptApproval.using(
	at org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript.evaluate(
	at org.jvnet.hudson.plugins.groovypostbuild.GroovyPostbuildRecorder.perform(
	at hudson.tasks.BuildStepMonitor$1.perform(
	at hudson.model.AbstractBuild$AbstractBuildExecution.perform(
	at hudson.model.AbstractBuild$AbstractBuildExecution.performAllBuildSteps(
	at hudson.model.Build$BuildExecution.post2(
	at hudson.model.AbstractBuild$
	at hudson.model.Run.execute(
	at hudson.model.ResourceController.execute(

Scripts using only whitelisted methods of manager

Scripts using only whitelisted methods of manager can run with using Groovy sandbox.
They can be validated only by checking "Use Groovy Sandbox".

Scripts using non-whitelisted methods

Scripts using non-whitelisted methods of manager or methods not of manager requires
approval of administrators.

Administrators should check and approve those scripts in Manage Jenkins > In-process Script Approval.

Scripts using external jar files

If you refer external jar files from your scripts, you need to have those jar files approved by administartors.

Administrators should check and approve those jar files in Manage Jenkins > In-process Script Approval.

Scripts using external class directories

Script Security Plugin doesn't support class directories.

If you refer external class directories from your scripts, you should archive them into jar files.
It can be performed by running a following command:

jar -cf mylib.jar -C /path/to/classes .

You can use /path/to/mylib.jar as an additonal classpath for scripts.


The groovy script can use the variable manager, which provides various methods to decorate your builds.
Those methods can be classified into whitelisted methods and non-whitelisted methods.
You can always use Whitelisted methods, but you can use Non-whitelisted methods only when "Enable groovy postbuild security" is not enabled (version 1.X) or in scripts approved by administrators (since version 2.x)

Whitelisted methods

  • getEnvVariable(key) - get a variable value. (since 1.10)
  • getResult() - get a build result string (like SUCCESS, FAILURE) (since 2.2)
  • logContains(regexp) - returns true if the build log file contains a line matching regexp.
  • getLogMatcher(regexp) - returns a java.util.regex.Matcher for the first occurrence of regexp in the build log file.
  • addShortText(text) - puts a badge with a short text, using the default format.
  • addShortText(text, color, background, border, borderColor) - puts a badge with a short text, using the specified format.  For Colors supported, Google "html color names".
  • addBadge(icon, text) - puts a badge with the given icon and text. In addition to the 16x16 icons offered by Jenkins, groovy-postbuild provides the following icons (watch out for duplicates, see Example 5):

    - completed.gif
    - db_in.gif
    - db_out.gif
    - delete.gif
    - error.gif
    - folder.gif
    - green.gif
    - info.gif
    - red.gif
    - save.gif
    - success.gif
    - text.gif
    - warning.gif
    - yellow.gif

  • addBadge(icon, text, link) - like addBadge(icon, text), but the Badge icon then actually links to the given link (since 1.8)
  • addInfoBadge(text) - puts a badge with info icon and the given text.
  • addWarningBadge(text) - puts a badge with warning icon and the given text.
  • addErrorBadge(text) - puts a badge with error icon and the given text.
  • removeBadges() - removes all badges from the current build. It is often used with setBuildNumber.
  • removeBadge(index) - removes the badge with the given index. It is often used with setBuildNumber.
  • buildUnstable() - sets the build result to UNSTABLE.
  • buildFailure() - sets the build result to FAILURE.
  • buildSuccess() - sets the build result to SUCCESS.
  • buildIsA(klass) - test the build is a specified class (since 2.0)

Non-whitelisted methods

Methods returning non-primitive objects aren't whitelisted as groovy-postbuild doesn't ensure every methods of those objects are safe.

  • envVars - the build variables map. You can get a variable value with

    You shouldn't update values. This isn't whitelisted, and it is recommended to use getEnvVariable(key) instead. (since 1.10)

  • contains(file, regexp) - returns true if the given file contains a line matching regexp. Not whitelisted as it allows users access any files (for example, a file containing passwords).
  • getMatcher(file, regexp) - returns a java.util.regex.Matcher for the first occurrence of regexp in the given file.
  • setBuildNumber(number) - sets the build with the given number as current build. The current build is the target of all methods that add or remove badges and summaries or change the build result.
  • createSummary(icon) - creates an entry in the build summary page and returns a summary object corresponding to this entry. The icon must be one of the 48x48 icons offered by Jenkins. You can append text to the summary object by calling its appendText methods. Be careful appending HTML-unescaped texts as they can be harmful.
    • appendText(text, escapeHtml)
    • appendText(text, escapeHtml, bold, italic, color)
  • removeSummaries() - removes all summaries from the current build.
  • removeSummary(index) - removes the summary with the given index.

Rest interfaces

It is also possible to delete badges and summaries by using the following links:

  • remove all badges:
    • http://your-jenkins/job/your-job/build-number/parent/parent/plugin/groovy-postbuild/removeBadges
  • remove all summaries:
    • http://your-jenkins/job/your-job/build-number/parent/parent/plugin/groovy-postbuild/removeSummaries
  • remove the badge with the given index:
    • http://your-jenkins/job/your-job/build-number/parent/parent/plugin/groovy-postbuild/removeBadge?index=idx
  • remove the summary with the given index:
    • http://your-jenkins/job/your-job/build-number/parent/parent/plugin/groovy-postbuild/removeSummary?index=idx

Example usages

Example 1

The script below puts a warning badge and mark the build as unstable if it detects that deprecated methods were used.

if(manager.logContains(".*uses or overrides a deprecated API.*")) {
    manager.addWarningBadge("Thou shalt not use deprecated methods.")
    manager.createSummary("warning.gif").appendText("<h1>You have been warned!</h1>", false, false, false, "red")

Example 2

Suppose we have a parameterized build, which uses the boolean parameter storeToDB in order to instruct the build to store some artifacts into the database. The script below puts a badge next to the builds for which this parameter is set.

if("true".equals("storeToDB"))) {
    manager.addBadge("db_in.gif", "Stored to DB")

Example 3

Suppose we have a parameterized build, which uses the string parameter version. The script below puts a short text indicating the value of this parameter next to successful and unstable builds.

if( {

Example 4

The script below determines how long it took to build the project and displays the corresponding value as a short text next to each build.

def matcher = manager.getLogMatcher(".*Total time: (.*)\$")
if(matcher?.matches()) {
    manager.addShortText(, "grey", "white", "0px", "white")

Example 5

For badges, you can choose from the 16x16 icons provided by Jenkins or from the icons provided by this plugin. Some of the names of groovy-postbuild icons conflict with the names of Jenkins icons (e.g. yellow.gif). For these icons, you have to provide the complete path (e.g. /images/16x16/yellow.gif), in case you want a badge with the Jenkins icon. You can also use icons provided by other plugins (e.g. Green Balls), by specifying the complete path to the icon.

manager.addBadge("star-gold.gif", "icon from Jenkins")
manager.addBadge("yellow.gif", "icon from groovy-postbuild plugin")
manager.addBadge("/images/16x16/yellow.gif", "icon from Jenkins")
manager.addBadge("/plugin/greenballs/16x16/green.gif", "icon from greenballs plugin")

Example 6

The script below displays on the build summary page all classes that use Sun proprietary API.

pattern = ~/.*src\/main\/java\/(.*)\.java:[^ ]* (.*) is Sun proprietary API and may be removed in a future release.*/
def map = [:] { line ->
    matcher = pattern.matcher(line)
    if(matcher.matches()) {
        ownClass ="/", ".")
        sunClass =
        map[ownClass] = sunClass
if(map.size() > 0) {
    summary = manager.createSummary("warning.gif")
    summary.appendText("Classes using Sun proprietary API:<ul>", false)
    map.each {
        summary.appendText("<li><b>$it.key</b> - uses $it.value</li>", false)
    summary.appendText("</ul>", false)

Example 7

The script below removes all badges and summaries from previous builds.

currentBuildNumber =
for(i=1; i<currentBuildNumber; i++) {
    if(manager.setBuildNumber(i)) {

Example 8

The script below marks the running build as deployed and the previous build as undeployed.

manager.createSummary("gear2.gif").appendText("<h2>Successfully deployed</h2>", false)

currentBuildNumber =
if(manager.setBuildNumber(currentBuildNumber - 1)) {
   actions =
    actions.each { action ->
        if (action.metaClass.hasProperty(action, "text") && action.text.contains("deployed")) {
    currDate = new Date().dateTimeString
    manager.addShortText("undeployed: $currDate", "grey", "white", "0px", "white")
    manager.createSummary("gear2.gif").appendText("<h2>Undeployed: $currDate</h2>", false, false, false, "grey")

Example 9 (thanks to Ken Bertelson)

The script below changes the description of the first failed test.

def tr =
def cr = tr.failedTests.get(0)
cr.description = "My CaseResult desc"

Example 10 (thanks to Frank Merrow)

Trivial, but hard to find the first time: Write a line to the job's Console Output:

manager.listener.logger.println("I want to see this line in my job's output");


Version 2.2.2 (Oct 17, 2015)

Version 2.2.1 (Aug 18, 2015)

Version 2.2 (Dec 19, 2014)

Version 2.1 (Oct 25, 2014)

Version 2.0 (Sep 21, 2014)

Version 1.10 (July 26, 2014)

  • added envVars and getEnvVariable(key)

Version 1.9 (April 29, 2014)

  • JENKINS-21924 Support run for matrix parent
  • change log level for each search from info to fine

Version 1.8 (August 22, 2012)

  • JENKINS-13024 Error in log indicating a missing descriptor
  • added clickable badge
  • Changed required Jenkins version to 1.466

Version 1.7 (May 2, 2012)

Version 1.6

  • JENKINS-9383 security - restrict access to internal objects

Can use now additional classpath for groovy postbuild scripts to have them in a central location. Scriptler Plugin?

Version 1.5 (November 5, 2011)

  • Remove a html tag from the config page which causes an error on IE 7 (JENKINS-10079)


To report a bug or request an enhancement to this plugin please create a ticket in JIRA.

JIRA Issues (11 issues)
Type Priority Key Summary
Bug Major JENKINS-31201 Groovy postbuild ignores RUN_SCRIPTS permission
New Feature Minor JENKINS-31038 Add whitelisted summary creation method
New Feature Minor JENKINS-27481 Use script from file
New Feature Major JENKINS-26918 Workflow support for Groovy Postbuild
Bug Major JENKINS-26251 Groovy Postbuild plugin shows error in project configuration
New Feature Minor JENKINS-25687 Add support for running scripts from the scriptler plugin
Task Major JENKINS-23116 Add tests for groovy-postbuild plugin
Bug Major JENKINS-18989 Cannot get Plugin to honor Java Jar added via "Additional groovy classpath"
New Feature Major JENKINS-15512 HTTPBuilder for Groovy Post Build
New Feature Minor JENKINS-14523 Expand icons one can use for summaries like already done for badges
Bug Major JENKINS-12010 manager.buildSuccess() doesn't work


plugin-post-build plugin-post-build Delete
plugin-groovy-related plugin-groovy-related Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment