diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2261ab8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,138 @@ +# Changelog + +## Version 2.5 (Jun 24, 2019) + +- Requires Jenkins 2.121.1 or later. +- New feature: `addHtmlBadge` is available [JENKINS-57917](https://issues.jenkins.io/browse/JENKINS-57917) - + + ``` syntaxhighlighter-pre + manager.addHtmlBadge('Italic text'); + ``` + +- groovy-postbuild no longer requires Overall/Administer permission: [JENKINS-54262](https://issues.jenkins.io/browse/JENKINS-54262) - It caused problems when used with [Authorize Project plugin](https://plugins.jenkins.io/authorize-project/) +- Suppress "WARNING: Avoid calling getLogFile on ..." when used in pipeline jobs. + +## Version 2.4.3 (Nov 18, 2018) + +- FIX: removeSummary / removeSummaries doesn't work (throw UnsupportedOperationException) ([JENKINS-54184](https://issues.jenkins.io/browse/JENKINS-54184)) + +## Version 2.4.2 (Aug 8, 2018) + +- FIX: removeBadge / removeBadges doesn't work (throw UnsupportedOperationException) ([JENKINS-52043](https://issues.jenkins.io/browse/JENKINS-52043)) + +## Version 2.4.1 (May 4, 2018) + +- Have [Build Monitor Plugin](https://plugins.jenkins.io/build-monitor-plugin/) not cause errors. + ([JENKINS-50420](https://issues.jenkins.io/browse/JENKINS-50420)) + - Introduced fake `GroovyPostbuildAction`. + - The feature of build-monitor to cooperate with groovy-postbuild doesn't work yet. It requires an upcoming release of build-monitor plugin to have it work again. + +## Version 2.4 (Mar 25, 2018) + +- Requires Jenkins 2.60.3 or later +- Extract badge and summary features to [Badge plugin](https://plugins.jenkins.io/badge) + ([JENKINS-43992](https://issues.jenkins.io/browse/JENKINS-43992)). + - You can use badge and summary features in pipeline only with badge-plugin. See [Badge Plugin](https://plugins.jenkins.io/badge/) for more details. +- Sanitize HTML in the badges. + - You no longer be able to use HTML expressions in badge contents. +- **Don't upgrade to this version if you use [Build Monitor Plugin](https://plugins.jenkins.io/build-monitor-plugin/).** + - Groovy-postbuild-2.4 breaks build-moitor-1.12 or earlier. Sorry. + - Please postpone upgrading groovy-postbuild till fixing this issue: + [JENKINS-50420](https://issues.jenkins.io/browse/JENKINS-50420) + - No new features in groovy-postbuild-2.4, and you can use + groovy-postbuild-2.3.1. + - You can downgrade your groovy-postbuild in the Jenkins + Plugin Management page. + - You can download earlier versions of groovy-postbuild from + "Archives" link in + +- Some classes are migrated to badge-plugin. Please change classes in + your codes if you access those classes: + + | Old Class | New Class | + |-----------------------------------------------------------------------|-------------------------------------------------------| + | org.jvnet.hudson.plugins.groovypostbuild.GroovyPostbuildAction | com.jenkinsci.plugins.badge.action.BadgeAction | + | org.jvnet.hudson.plugins.groovypostbuild.GroovyPostbuildSummaryAction | com.jenkinsci.plugins.badge.action.BadgeSummaryAction | + +## Version 2.3.1 (Feb 7, 2016) + +- Dependency to pipeline (aka. workflow) is optional + ([JENKINS-32589](https://issues.jenkins.io/browse/JENKINS-32589)). + +## Version 2.3 (Dec 27, 2015) + +- Require Jenkins 1.609 or later +- Supports workflow + ([JENKINS-26918](https://issues.jenkins.io/browse/JENKINS-26918)) + - You can use `manager` in workflow scripts. + +## Version 2.2.2 (Oct 17, 2015) + +- Added MIT License + ([JENKINS-21270](https://issues.jenkins.io/browse/JENKINS-21270)) + +## Version 2.2.1 (Aug 18, 2015) + +- Improved the behavior with [Template Project + Plugin](https://wiki.jenkins.io/display/JENKINS/Template+Project+Plugin) + ([JENKINS-21276](https://issues.jenkins.io/browse/JENKINS-21276)) + - Prior versions disturbed the execution of [Template Project + Plugin](https://wiki.jenkins.io/display/JENKINS/Template+Project+Plugin) + when the build was failed (even if the groovy script succeeded). + +## Version 2.2 (Dec 19, 2014) + +- added getResult() as a whitelisted method + ([JENKINS-25738](https://issues.jenkins.io/browse/JENKINS-25738)) + +## Version 2.1 (Oct 25, 2014) + +- You can access other plugins in groovy scripts + ([JENKINS-14154](https://issues.jenkins.io/browse/JENKINS-14154)) + +## Version 2.0 (Sep 21, 2014) + +- Require Jenkins 1.509.4 or later +- Introduced [Script Security + Plugin](https://wiki.jenkins.io/display/JENKINS/Script+Security+Plugin). + ([JENKINS-15212](https://issues.jenkins.io/browse/JENKINS-15212)) + - You need reconfigure your projects or approve scripts. Have a + look at [\#Migration from + 1.X](https://wiki.jenkins.io/display/JENKINS/Groovy+Postbuild+Plugin#GroovyPostbuildPlugin-Migrationfrom1.X) +- Added `manager.buildIsA(klcass)`. + ([JENKINS-24694](https://issues.jenkins.io/browse/JENKINS-24694)) + +## Version 1.10 (July 26, 2014) + +- added `envVars` and `getEnvVariable(key)` + +## Version 1.9 (April 29, 2014) + +- [JENKINS-21924](https://issues.jenkins.io/browse/JENKINS-21924) + Support run for matrix parent +- change log level for each search from info to fine + +## Version 1.8 (August 22, 2012) + +- Require Jenkins version 1.466 or later +- [JENKINS-13024](https://issues.jenkins.io/browse/JENKINS-13024) + Error in log indicating a missing descriptor +- added clickable badge + +## Version 1.7 (May 2, 2012) + +- [JENKINS-13024](https://issues.jenkins.io/browse/JENKINS-13024) + Error in log indicating a missing descriptor + +## Version 1.6 + +- [JENKINS-9383](https://issues.jenkins.io/browse/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](https://issues.jenkins.io/browse/JENKINS-10079)) diff --git a/README.md b/README.md new file mode 100644 index 0000000..8a095fd --- /dev/null +++ b/README.md @@ -0,0 +1,345 @@ +# Groovy postbuild plugin + +This plugin executes a groovy script in the Jenkins JVM as a post-build action (a publisher) . +Typically, the script checks some conditions and updates the build result, puts badges next to the build in the build history, and/or displays information on the build summary page. + +## Usage + +The groovy script can use the variable `manager`, which provides various methods to decorate your builds. +Those methods can be classified into *approved methods* and *non-approved methods*. +You can always use *approved methods*, but you can use *non-approved methods* only when "Enable groovy postbuild security" scripts are approved by administrators. + +### Approved methods + +- `getEnvVariable(key)` - get a variable value. +- `getResult()` - get a build result string (like SUCCESS, FAILURE) + +#### Log methods + +- `logContains(regexp)` - returns true if the build log file contains a line matching *regexp*. +- `getLogMatcher(regexp)` - returns a [java.util.regex.Matcher](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Matcher.html) for the first occurrence of *regexp* in the build log file. + +#### Short text methods + +- `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. + Supports html color names. + +#### Badge methods + +- `addBadge(icon, text, link)` - like addBadge(icon, text), but the Badge icon then actually links to the given link +- `addInfoBadge(text)` - puts a badge with ![](docs/images/info.gif) info icon and the given text. +- `addWarningBadge(text)` - puts a badge with ![](docs/images/warning.gif) warning icon and the given text. +- `addErrorBadge(text)` - puts a badge with ![](docs/images/error.gif) error icon and the given text. +- `addHtmlBadge(html)` - puts a badge with html source. Unsafe html codes will be removed. +- `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`. +- `addBadge(icon, text)` - puts a badge with the given icon and text. + Provides the following icons: + + > ![](docs/images/completed.gif) - completed.gif + > + > ![](docs/images/db_in.gif) - db\_in.gif + > + > ![](docs/images/db_out.gif) - db\_out.gif + > + > ![](docs/images/delete.gif) - delete.gif + > + > ![](docs/images/error.gif) - error.gif + > + > ![](docs/images/folder.gif) - folder.gif + > + > ![](docs/images/green.gif) - green.gif + > + > ![](docs/images/info.gif) - info.gif + > + > ![](docs/images/red.gif) - red.gif + > + > ![](docs/images/save.gif) - save.gif + > + > ![](docs/images/success.gif) - success.gif + > + > ![](docs/images/text.gif) - text.gif + > + > ![](docs/images/warning.gif) - warning.gif + > + > ![](docs/images/yellow.gif) - yellow.gif + +#### Build result methods + +- `buildUnstable()` - sets the build result to *UNSTABLE*. +- `buildFailure()` - sets the build result to *FAILURE*. +- `buildSuccess()` - sets the build result to *SUCCESS*. + +#### Job type methods + +- `buildIsA(klass)` - test the build is a specified class + +### Non-approved methods + +Methods returning non-primitive objects aren't approved. +The groovy postbuild plugin doesn't ensure that the methods of the returned object are safe. + +- `build` - the current build - [javadoc](https://javadoc.jenkins-ci.org/hudson/model/AbstractBuild.html) +- `hudson` - the current controller instance - [javadoc](https://javadoc.jenkins-ci.org/hudson/model/Hudson.html) +- `listener` - the build listener - [javadoc](https://javadoc.jenkins-ci.org/hudson/model/BuildListener.html) + +#### Environment variables + +- `envVars` - the build variables map. You can get a variable value with + + ``` syntaxhighlighter-pre + manager.envVars['varname'] + ``` + + Do not update the returned values. + This method is not recommended for any use. + Use `getEnvVariable(key)` instead. + +#### File content matching + +- `contains(file, regexp)` - returns true if the given file contains a line matching *regexp*. + Not approved as it allows users access any files (for example, a file containing passwords). +- `getMatcher(file, regexp)` - returns a [java.util.regex.Matcher](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Matcher.html) for the first occurrence of *regexp* in the given file. + +#### Build number control + +- `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. + +#### Summary modification + +- `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](https://github.com/jenkinsci/jenkins/tree/master/war/src/main/webapp/images/48x48) + 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. + +### 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. + +``` syntaxhighlighter-pre +if(manager.logContains(".*uses or overrides a deprecated API.*")) { + manager.addWarningBadge("Thou shalt not use deprecated methods.") + manager.createSummary("warning.gif").appendText("

Warned!

", false, false, false, "red") + manager.buildUnstable() +} +``` + +[TABLE] + +#### 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. + +``` syntaxhighlighter-pre +if("true".equals(manager.build.buildVariables.get("storeToDB"))) { + manager.addBadge("db_in.gif", "Stored to DB") +} +``` + +![](docs/images/example2.gif) + +#### 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. + +``` syntaxhighlighter-pre +if(manager.build.result.isBetterOrEqualTo(hudson.model.Result.UNSTABLE)) { + manager.addShortText("v${manager.build.buildVariables.get('version')}") +} +``` + +![](docs/images/example3.gif) + +#### 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. + +``` syntaxhighlighter-pre +def matcher = manager.getLogMatcher(".*Total time: (.*)\$") +if(matcher?.matches()) { + manager.addShortText(matcher.group(1), "grey", "white", "0px", "white") +} +``` + +![](docs/images/example4.gif) + +#### Example 5 + +For badges, you can choose from the icons provided by this plugin. +If the name of a groovy-postbuild icon conflicts with the name of a Jenkins icon, provide the complete path to the icon. + +``` syntaxhighlighter-pre +manager.addBadge("yellow.gif", "icon from groovy-postbuild plugin") +``` + +![](docs/images/example5.gif) + +#### Example 6 + +The script below displays on the build summary page all classes that use Sun proprietary API. + +``` syntaxhighlighter-pre +pattern = ~/.*src\/main\/java\/(.*)\.java:[^ ]* (.*) Sun proprietary API.*/ +def map = [:] +manager.build.logFile.eachLine { line -> + matcher = pattern.matcher(line) + if(matcher.matches()) { + ownClass = matcher.group(1).replaceAll("/", ".") + sunClass = matcher.group(2) + map[ownClass] = sunClass + } +} +if(map.size() > 0) { + def summary = manager.createSummary("warning.gif") + summary.appendText("Classes using Sun proprietary API:", false) +} +``` + +![](docs/images/example6.gif) + +#### Example 7 + +The script below removes all badges and summaries from previous builds. + +``` syntaxhighlighter-pre +currentBuildNumber = manager.build.number +for(i=1; iSuccessfully deployed", false) + +currentBuildNumber = manager.build.number +if(manager.setBuildNumber(currentBuildNumber - 1)) { + actions = manager.build.actions + actions.each { action -> + if (action.metaClass.hasProperty(action, "text") && action.text.contains("deployed")) { + actions.remove(action) + } + } + currDate = new Date().dateTimeString + manager.addShortText("undeployed: $currDate", "grey", "white", "0px", "white") + manager.createSummary("gear2.gif").appendText("

Undeployed: $currDate

", false, false, false, "grey") +} +``` + +![](docs/images/example8.gif) + +#### Example 9 (thanks to Ken Bertelson) + +The script below changes the description of the first failed test. + +``` syntaxhighlighter-pre +def tr = manager.build.testResultAction.result +def cr = tr.failedTests.get(0) +cr.description = "My CaseResult desc" +``` + +#### Example 10 (thanks to Frank Merrow) + +Write a line to the job's console output: + +``` syntaxhighlighter-pre +manager.listener.logger.println("I want to see this line in my job's output"); +``` + +## Issues + +To report a bug or request an enhancement to this plugin please create a ticket in JIRA (you need to login or to sign up for an account). +Please review and follow the instructions in ["How to report an issue"](https://www.jenkins.io/participate/report-issue/). + +- [Open Issues](https://issues.jenkins.io/issues/?jql=resolution%20is%20EMPTY%20and%20component%3D15685) +- [Bug report or enhancement request](https://www.jenkins.io/participate/report-issue/redirect/#15685) + +## Changelog in [GitHub Releases](https://github.com/jenkinsci/git-client-plugin/releases) + +Release notes have been recorded in https://github.com/jenkinsci/git-client-plugin/releases[GitHub] since release 2.7.0. +Prior release notes were recorded in the repository [change log](). + +## Migration from 1.X + +Beginning with version 2.0 (September 2014), Groovy Postbuild plugin introduces [Script Security Plugin](https://plugins.jenkins.io/script-security/). +Administrators can prevent users without proper privileges from running harmful scripts. + +For details, see [Script Security Plugin](https://plugins.jenkins.io/script-security/). +This doesn't affect [Jenkins without security enabled](https://www.jenkins.io/doc/book/security/securing-jenkins/) 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 +must update the configuration 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(ScriptApproval.java:398) + at org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SecureGroovyScript.evaluate(SecureGroovyScript.java:165) + at org.jvnet.hudson.plugins.groovypostbuild.GroovyPostbuildRecorder.perform(GroovyPostbuildRecorder.java:343) + at hudson.tasks.BuildStepMonitor$1.perform(BuildStepMonitor.java:20) + at hudson.model.AbstractBuild$AbstractBuildExecution.perform(AbstractBuild.java:785) + at hudson.model.AbstractBuild$AbstractBuildExecution.performAllBuildSteps(AbstractBuild.java:757) + at hudson.model.Build$BuildExecution.post2(Build.java:183) + at hudson.model.AbstractBuild$AbstractBuildExecution.post(AbstractBuild.java:706) + at hudson.model.Run.execute(Run.java:1690) + at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:46) + at hudson.model.ResourceController.execute(ResourceController.java:88) + at hudson.model.Executor.run(Executor.java:246) + +### Scripts using only approved methods of manager + +Scripts using only [approved methods of manager](/#Approved-Methods) can run with the Groovy sandbox. +They can be validated by running with "Use Groovy Sandbox" checked in the job definition. + +![](docs/images/scriptsecurity-enablesandbox.png) + +### Scripts using non-approved methods + +Scripts using [non-approved methods of manager](/#Non-approved-methods) or methods not of manager require administrator approval. + +Administrators should check and approve those scripts in Manage Jenkins \> In-process Script Approval. + +![](docs/images/scriptsecurity-approvescript.png) + +### Scripts using external jar files + +If you refer to external jar files from your scripts, those jar files must be approved by an administrator. + +Administrators should check and approve those jar files in Manage \> In-process Script Approval. + +![](docs/images/scriptsecurity-approvejar.png) + +### Scripts using external class directories + +[Script Security Plugin](https://plugins.jenkins.io/script-security/) doesn't support class directories. + +If you refer to external class directories from your scripts, you must archive them in 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. diff --git a/docs/images/completed.gif b/docs/images/completed.gif new file mode 100644 index 0000000..23c97f0 Binary files /dev/null and b/docs/images/completed.gif differ diff --git a/docs/images/db_in.gif b/docs/images/db_in.gif new file mode 100644 index 0000000..75978cb Binary files /dev/null and b/docs/images/db_in.gif differ diff --git a/docs/images/db_out.gif b/docs/images/db_out.gif new file mode 100644 index 0000000..c9dddb5 Binary files /dev/null and b/docs/images/db_out.gif differ diff --git a/docs/images/delete.gif b/docs/images/delete.gif new file mode 100644 index 0000000..0ae6dec Binary files /dev/null and b/docs/images/delete.gif differ diff --git a/docs/images/error.gif b/docs/images/error.gif new file mode 100644 index 0000000..2ff6678 Binary files /dev/null and b/docs/images/error.gif differ diff --git a/docs/images/example2.gif b/docs/images/example2.gif new file mode 100644 index 0000000..ad78a8d Binary files /dev/null and b/docs/images/example2.gif differ diff --git a/docs/images/example3.gif b/docs/images/example3.gif new file mode 100644 index 0000000..d9681f8 Binary files /dev/null and b/docs/images/example3.gif differ diff --git a/docs/images/example4.gif b/docs/images/example4.gif new file mode 100644 index 0000000..3d8fe93 Binary files /dev/null and b/docs/images/example4.gif differ diff --git a/docs/images/example5.gif b/docs/images/example5.gif new file mode 100644 index 0000000..ca42795 Binary files /dev/null and b/docs/images/example5.gif differ diff --git a/docs/images/example6.gif b/docs/images/example6.gif new file mode 100644 index 0000000..0a1f2d5 Binary files /dev/null and b/docs/images/example6.gif differ diff --git a/docs/images/example8.gif b/docs/images/example8.gif new file mode 100644 index 0000000..f1c40ba Binary files /dev/null and b/docs/images/example8.gif differ diff --git a/docs/images/folder.gif b/docs/images/folder.gif new file mode 100644 index 0000000..21322e0 Binary files /dev/null and b/docs/images/folder.gif differ diff --git a/docs/images/green.gif b/docs/images/green.gif new file mode 100644 index 0000000..e8e295f Binary files /dev/null and b/docs/images/green.gif differ diff --git a/docs/images/info.gif b/docs/images/info.gif new file mode 100644 index 0000000..b484d9b Binary files /dev/null and b/docs/images/info.gif differ diff --git a/docs/images/red.gif b/docs/images/red.gif new file mode 100644 index 0000000..c201c83 Binary files /dev/null and b/docs/images/red.gif differ diff --git a/docs/images/save.gif b/docs/images/save.gif new file mode 100644 index 0000000..499dd0c Binary files /dev/null and b/docs/images/save.gif differ diff --git a/docs/images/scriptsecurity-approvejar.png b/docs/images/scriptsecurity-approvejar.png new file mode 100644 index 0000000..8e56563 Binary files /dev/null and b/docs/images/scriptsecurity-approvejar.png differ diff --git a/docs/images/scriptsecurity-approvescript.png b/docs/images/scriptsecurity-approvescript.png new file mode 100644 index 0000000..14fd7c0 Binary files /dev/null and b/docs/images/scriptsecurity-approvescript.png differ diff --git a/docs/images/scriptsecurity-enablesandbox.png b/docs/images/scriptsecurity-enablesandbox.png new file mode 100644 index 0000000..745f878 Binary files /dev/null and b/docs/images/scriptsecurity-enablesandbox.png differ diff --git a/docs/images/success.gif b/docs/images/success.gif new file mode 100644 index 0000000..1d9c323 Binary files /dev/null and b/docs/images/success.gif differ diff --git a/docs/images/text.gif b/docs/images/text.gif new file mode 100644 index 0000000..efa7a38 Binary files /dev/null and b/docs/images/text.gif differ diff --git a/docs/images/warning.gif b/docs/images/warning.gif new file mode 100644 index 0000000..a01bb24 Binary files /dev/null and b/docs/images/warning.gif differ diff --git a/docs/images/yellow.gif b/docs/images/yellow.gif new file mode 100644 index 0000000..799fd23 Binary files /dev/null and b/docs/images/yellow.gif differ diff --git a/pom.xml b/pom.xml index 767a334..d514f1f 100644 --- a/pom.xml +++ b/pom.xml @@ -13,7 +13,7 @@ hpi Groovy Postbuild - https://wiki.jenkins.io/display/JENKINS/Groovy+Postbuild+Plugin + https://github.com/jenkinsci/groovy-postbuild-plugin