Groovy plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID groovy Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.16
Apr 07, 2014
1.532
token-macro (version:1.4, optional)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Vojtech Juranek (id: vjuranek)
Usage Installations 2013-Apr 3278
2013-May 3366
2013-Jun 3473
2013-Jul 3664
2013-Aug 3744
2013-Sep 3899
2013-Oct 4198
2013-Nov 4231
2013-Dec 4256
2014-Jan 4616
2014-Feb 4863
2014-Mar 5056

This plugin adds the ability to directly execute Groovy code.

Configuration

To configure available Groovy installation on your system, go to Jenkins configuration page, find section 'Groovy' and fill the form as shown bellow.


Usage

To create Groovy-based project, add new free-style project and select "Execute Groovy script" in the Build section, select previously configured Groovy installation and then type your command, or specify your script file name. In the second case path taken is relatively from the project workspace directory.


The plugin also adds the functionality of the Script Console to the project configuration page. You can schedule your system management script...


...and then observe progress in the build log.


Groovy Script vs System Groovy Script

The plain "Groovy Script" is run in a forked JVM, on the slave where the build is run. It's the basically the same as running the "groovy" command and pass in the script.

The system groovy script, OTOH, runs inside the Hudson master's JVM. Thus it will have access to all the internal objects of Hudson, so you can use this to alter the state of Hudson. It is similar to the Jenkins Script Console functionality.

Security

System groovy jobs has access to whole Jenkins, therefore only users with admin rights can  add system groovy build step and configure the system groovy script. Permissions are not checked when the build is triggered (i.e. also uses without admin rights can also run the script). The idea is to allow users run some well defined (defined by admin) system tasks when they need it (e.g. put slave offline/online, when user wants to start some debugging on slave). To have Jenkins instance secure, the support for Token macro plugin has to be switched off, see section bellow.

Token macro plugin support

Groovy plugin provides support for  Token Macro Plugin. Expression is GROOVY with parameter script:

${GROOVY,script = "return hudson.model.Hudson.instance.pluginManager.plugins"}

By default, the support for token macro pressing is switched off and has to be switch on in global config page.

If token macro processing via Token Macro Plugin is allowed, the evaluation of macro is done in System Groovy, therefore any user can run arbitrary system script, regardless he has administer permission!

Examples

Retrieving parameters and triggering another build

Execute a system Groovy script like:

import hudson.model.*
import hudson.AbortException
import hudson.console.HyperlinkNote
import java.util.concurrent.CancellationException

// Retrieve parameters of the current build
def foo = build.buildVariableResolver.resolve("FOO")
println "FOO=$foo"

// Start another job
def job = Hudson.instance.getJob('MyJobName')
def anotherBuild
try {
    def params = [
      new StringParameterValue('FOO', foo),
    ]
    def future = job.scheduleBuild2(0, new Cause.UpstreamCause(build), new ParametersAction(params))
    println "Waiting for the completion of " + HyperlinkNote.encodeTo('/' + job.url, job.fullDisplayName)
    anotherBuild = future.get()
} catch (CancellationException x) {
    throw new AbortException("${job.fullDisplayName} aborted.")
}
println HyperlinkNote.encodeTo('/' + anotherBuild.url, anotherBuild.fullDisplayName) + " completed. Result was " + anotherBuild.result

// Check that it succeeded
build.result = anotherBuild.result
if (anotherBuild.result != SUCCESS && anotherBuild.result != UNSTABLE) {
    // We abort this build right here and now.
    throw new AbortException("${anotherBuild.fullDisplayName} failed.")
}

// Do something with the output.
// On the contrary to Parameterized Trigger Plugin, you may now do something from that other build instance.
// Like the parsing the build log (see http://javadoc.jenkins-ci.org/hudson/model/FreeStyleBuild.html )
// You probably may also wish to update the current job's environment.
build.addAction(new ParametersAction(new StringParameterValue('BAR', '3')))

Retrieve properties

To retrieve properties defined in the Properties field use:

System.getProperty('FOO')

Changelog

Upcomming changes
Release 1.16 (2014-04-07)
  • Upgrade to @DataBoundConstructor (issue #6797)
  • Fixed typo in warrning message (pull12)
Release 1.15 (2014-01-31)
  • Syntax highlighting
  • Syntax validation button
  • Prepare for Jenkins core upgrade to Groovy 2.x (pull9)
Release 1.14 (2013-07-02)
  • Right to run the System Groovy script changed from ADMINISTER to RUN_SCRIPTS (pull7)
Release 1.13 (2013-03-01)
  • Added build context (build, launcher, listener) into system groovy build step (pull6)
Release 1.12 (2012-03-08)
  • Fixed configuration of Token macro (pull5)
Release 1.11 (2012-02-26)
  • Enabled env. variables expansion class path, groovy and script parameters
Release 1.10 (2012-02-09)
  • Fixed possible job configuration corruption when user isn't admin (issue #12080)
  • Avoid NPE, add fallback if groovy executable is misoncifured (issue #11652)
Release 1.9 (2011-09-14)
Release 1.8 (2011-05-13)
  • Fixed a configuration persistence problem that can create huge config.xml
Release 1.7 (2011-03-09)
Release 1.6 (2011-02-08)
  • Fixed security issue
Release 1.5 (2010-11-10)
Release 1.4 (2009-12-29)
  • Improve error message for missing groovy executable
  • Update uses of deprecated APIs
Release 1.2
  • Added possibility to specify properties and script parameters.
  • Added script source choice (file/command) for system groovy scripts.
  • Used .exe instead of .bat on Windows (as suggested by Scott Armit).
  • Added configuration option for classpath and initial variable bindings for
    system groovy scripts.

Known bugs

  • Configuring more builders at once actually doesn't absolutely work. If you need more groovy builders in your project, you have to configure them one by one and always save project configuration before you add new one.

Labels

Edit
plugin-builder plugin-builder Delete
token-producer token-producer 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