Plugin Information |
---|
View Groovy on the plugin site for more information. |
Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:
Configuration
To configure available Groovy installation on your system, go to Jenkins configuration page, find section 'Groovy' and fill the form as shown bellow.
If you don't configure any Groovy installation and select (Default)
option in a job, the plugin will fallback into calling just the groovy
command, assuming you have groovy
binary on the default path on given machine.
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.
Jenkins 1.x:
Jenkins 2.x:
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 on the other hand runs inside the Jenkins master's JVM. Thus it will have access to all the internal objects of Jenkins, so you can use this to alter the state of Jenkins. 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 below.
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 != Result.SUCCESS && anotherBuild.result != 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')
Usage with pipeline
Currently the plugin does not support pipeline syntax. One workaround from Unknown User (alexander_samoylov) was mentioned here: https://stackoverflow.com/a/58381147/4807875.
Changelog
Release 2.2 (2019-03-06)
Release 2.1 (2019-01-28)
Release 2.0 (2017-04-10)
- Arbitrary code execution by unprivileged user (SECURITY-292)
- continue with code cleanup - fixed Findbugs issues
Release 1.30 (2016-11-18)
- XSS protection
- code cleanup
Release 1.28, 1.29 (2016-01-05)
- code cleanup
Release 1.27 (2015-08-05)
Callable
roles are properly checked
Release 1.26 (2015-07-27)
- Ensured correct position of class path option (JENKINS-29577)
- Improved help (pr #18)
Release 1.25 (2015-05-11)
- Made default choice also for System Groovy script to avoid zero height of textarea (JENKINS-25455)
- Add help file for Groovy version (JENKINS-12988)
- Made setting Groovy installations thread-safe (JENKINS-28287)
Release 1.24 (2014-11-09)
- Ensure non-zero height of Groovy command text box, making it default choice when adding new build step (JENKINS-25455)
Release 1.23 (2014-10-27)
- Set up correct GROOVY_HOME environment variable (JENKINS-25275)
Release 1.22 (2014-09-30)
- Fixed slashes conversion in script parameters (JENKINS-24870)
Release 1.21 (2014-09-18)
- Allow spaces in script parameters (JENKINS-24757)
Release 1.20 (2014-07-30)
- Unable to specify multiple jars on class path for a system groovy script (JENKINS-23997)
Release 1.19 (2014-07-07)
- Better parsing of parameters passed to Groovy binary, Apache commons-exec used for parsing (JENKINS-23617)
Release 1.18 (2014-05-13)
- NPE fixes (JENKINS-17171)
Release 1.17 (2014-05-09)
- Allow whitespaces in properties (passed via -D switch) (pull13)
Release 1.16 (2014-04-07)
- Upgrade to @DataBoundConstructor (JENKINS-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 (JENKINS-12080)
- Avoid NPE, add fallback if groovy executable is misoncifured (JENKINS-11652)
Release 1.9 (2011-09-14)
- Auto installer (JENKINS-7113 and JENKINS-10920)
- Fixed error message on global config page (JENKINS-10768)
- Expansion of job parameters (JENKINS-10525)
- Full access to JAVA_OPTS (i.e. parameters like -Xmx can be set up)
- Editable class path
Release 1.8 (2011-05-13)
- Fixed a configuration persistence problem that can create huge config.xml
Release 1.7 (2011-03-09)
- Added support for Token Macro Plugin
Release 1.6 (2011-02-08)
- Fixed security issue
Release 1.5 (2010-11-10)
- Classloader for actual System Groovy (JENKINS-6068)
- Allowed groovy.bat in addition to groovy.exe (JENKINS-6839)
- Temp files are removed (JENKINS-3269)
- Hudson global properties are expanded in groovy script file path (JENKINS-8048)
- Upgraded to 1.358 (JENKINS-6081)
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.
45 Comments
Unknown User (smarmit)
Thanks for this plugin. I've found one issue however (Windows server); if the path to a groovy script passes args, then the full string is quoted. For example, in the "Groovy script file" field, you may have, "build.groovy one two" ('one' and 'two' being args).
The call to groovy.bat will look like, C:\Groovy-1.5.4\bin\groovy.bat "c:\hudson\jobs\groovy\workspace\build.groovy one two"
The result is an exception because groovy.bat processes everything in quotes as one long filename:
Caught: java.io.FileNotFoundException: C:\hudson\jobs\groovy\workspace\build.groovy one two (C:\hudson\jobs\groovy\workspace\build.groovy one two
There is a hacky workound, after your build script name, put double quotes. In my example, build.groovy" one two . This closes the first double-quote, and the last added one gets ignored.
Thanks
Unknown User (dvrzalik)
Yep, the file field isn't intended for script parameters. Next version should let you specify parameters without any hacks.
Unknown User (smarmit)
Ok, thank you for the information. One other thing I found if you're interested. Apparently 'groovy.bat' does not handle return codes well. So if you System.exit(1) for instance out of your 'groovy' code, Hudson will still report SUCCESS. It's not Hudson's fault, but groovy.bat. Some notes on the groovy web site mention that using the native launcher fixes this (groovy.exe versus groovy.bat). I downloaded your src and changed ".bat" to ".exe" and built the 'hpi' and it works such that my return codes are not ignored.
Regards and thanks again for this plugin!
Unknown User (dvrzalik)
Thanks, I don't use Windows so I don't have much chance to catch these problems. I updated the code to use groovy.exe.
Unknown User (smarmit)
Wow, thanks for the fast fix. I'm mostly a linux guy, but have to support some Windows stuff. Speaking of, I tried out the plugin on linux, and tried my "hack" to pass parameters, but linux being stricter about quotes, the hack doesn't work. So I added a scriptArgs textbox under the scriptFile textbox and it works great. I tested giving the path to a groovy file with spaces in it on windows, and it quoted properly: e.g. <path-to-groovy.exe> "C:\Documents and Settings\user\build.groovy" -option1 -option2
The code is a little hacky as it's my first attempt at the plugin code, but I can get it to you if you're interested. Thanks again.
Unknown User (jvizueta)
I want to access a project's parameters from the "This build is parameterized" option in the project configuration page, how can I get this done?
Thank you
Regards
Unknown User (ali.raza@macrovision.com)
How can I configure groovy in hudson. My groovy installation is on a windows.
My install location is
C:\Program Files\Groovy\Groovy-1.6.4
I have a SystemVariable in windows called GROOVY_HOME set to C:\Program Files\Groovy\Groovy-1.6.4
I have added this to the path as %GROOVY_HOME%\bin
In Hudson manage I am trying to specify the
groovy installation name as 'Groovy1.6.4'
GROOVY_HOME as C:\Program Files\Groovy\Groovy-1.6.4
as soon as I type this I get
HTTP Status 404 -
type Status report
message
description The requested resource () is not available.
Apache Tomcat/5.5.27
Also select 'execute groovy script' does not show the text box where I can specify the groovy script.
What am I doing wrong.
Thanks for your help.
Unknown User (mindcrime)
Great plugin, thanks! A couple of questions though... Is running a groovy script different from running a groovy "system command" in terms of what "stuff" is exposed to the groovy code? That is, the example listed above doesn't work for me when run as a Groovy script.. can I not get access to the hudson internals when running a Groovy script? What can you access when running Groovy scripts? Do you have visibility into any of the Hudson information about the project, build, etc? If so, how is it exposed to the Groovy code?
Thanks in advance for any and all help!
Unknown User (vladimir d)
Phillip Rhodes - If you create a "System Groovy Script" you can access the hudson instance like so:
I'm using it to find all my jobs (other than the one that's executing this script, which has a null SCM) like this:
But, I'm having a bear of a time figuring out how to get groovy access to the environment variables, specifically from the "this build is parameterized" variable that I've defined.
If anybody has any clues to how this is done I'd appreciate it.
//Vlad
Unknown User (vkodocha)
EDIT:
Ok after reading your comment a second time I don't think that the link will solve the problem you have. It seams to be the same problem I had but I found a workaround yesterday (its not so nice but it is working):
This will get you the values the user entered for the latest build of the given job, if this is the currently running job you will get the parameter for currently running job (tested with hudson 1.351).
Have a look at http://wiki.jenkins-ci.org/display/HUDSON/Display+job+parameters this should do what you want
greetings
vkodocha
Unknown User (marcolof)
After spending way too much time figuring this out, I found the following solution, which works fairly well for me (no need to submit <jobname>!)
This should produce something like the following:
There is some overlap between the two, but matrix/axises can only be found in the "specified" parameters/properties.
Unknown User (vkodocha)
Is it possible to access the properties set by a parametrized build form within a "Execute System Groovy script" (file or when directly entered in the text box). I can access the properties in an external groovy script ("Execute Groovy script") by going over the System.getenv() path. But when trying the same inside a system one the properties are not set in the environment.
I tried to add the properties with the "Variable bindings" by specifying testName=$NameOfParameter but this is also not working. Basically the plugin is not resolving $NameOfParameter to the value of this field.
I think the simplest solution would just be to add the properties from the parametrized build to the environment of the groovy script.
Unknown User (nperrier)
Same problem. Bindings work good with strings, but they don't seem to expand build parameters...is this the way it's supposed to work?
Unknown User (nperrier)
By the way, how about using a spellchecker for your help section chief :)
"Define varibale bingings (in the properties file format). Spefified variables can be addressed from the script."
Unknown User (vladimir d)
I finally got my script to fetch the parameterized build value, here's how:
hope this helps.
Unknown User (mcrooney)
You are my hero, thanks, that works!
Unknown User (dnozay)
added Parameterized System Groovy script page, here is a less hacky recipe :
gives (provided my build was started with MYFOOPARAM=foobar)
Unknown User (fsimo)
Since this script show me user and password on Console Script it doesn't works within a "system groovy script", it show SYSTEM/SYSTEM.
Any one knows who to know the user's credentials within a task?
Thanks!
/* CODE */
import org.acegisecurity.Authentication;
import org.acegisecurity.context.SecurityContextHolder;
println("Usuario: "+(String)hudson.model.User.current());
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
String g=auth.getCredentials();
println("Password: "+ g);
/* CODE */
Unknown User (dbaret)
I don't anderstand what is this problem.
I tried this :
println(hudson.model.User.current().getFullName());
it works under the admin script consol but not in an execute system script groovy command : I get SYSTEM and not my user name.
It's a bug?
Unknown User (geronimo)
How would I get the workspace of my current build?
Unknown User (geronimo)
via Thread.currentThread().executable.
Unknown User (wernight)
Sorry to ask, but how is
Thread.currentThread().executable
working for concurrent builds and multiple nodes/slaves?Unknown User (geronimo)
I wonder whether the "forked JVM/script" part of this plugin is particular useful?
Cause I can archive the very same by running a shell script like (as build job) like
To comfort various groovy installations, I could setup env variables like GROOVY_BIN_1, GROOVY_BIN_2 and so on and change script above into
So, why providing something which is already there?
Unknown User (geronimo)
After having playing around with this plugin, I consider it a waste of time - to put it mildly.
As an example, Jenkins variables are resolved in <scriptSource /> but NOT in </scriptParameters />.
Unknown User (gisela_sn)
Anyone know how to use the variable bindings for system groovy scrpits?
Unknown User (wernight)
First you'll need to access the build instance, see Parameterized System Groovy script
Then supposing it's a standard free style job, see http://javadoc.jenkins-ci.org/hudson/model/FreeStyleBuild.html
Unknown User (sunstorm)
I'd like to invoke (i.e. submit to the build queue) a parameterised job with two parameters, A and B. I'd like to invoke the job using the default value for A and supply an overridden value for B. I'd also like to wait for the submitted job to complete. Can anyone provide explicit code for doing this? Thanks.
Unknown User (wernight)
A system Groovy script may help, see
scheduleBuild2
may be the safest choice. Something like:Unknown User (edalquist)
Generic system script that can be used to fail the current build of other builds are not successful
Unknown User (wernight)
Does anyone know how to define parameters or environment variables for the current build in a System Groovy script?
Reason: System Groovy runs on master, but can access other builds info and trigger builds. Normal Groovy runs on the node. How to transmit info between both?
Unknown User (nickg)
To set properties using the System Groovy Script:
Hope that helps.
If you need to run it as a normal Groovy script, you'll probably need to do the following: http://stackoverflow.com/questions/9996315/jenkins-packages-on-groovy-classpath
Unknown User (nickg)
Or even...
Unknown User (ivan_zolotuhin)
Don't want to lost my script, may be somebody will need it. Lot of things this can do (most of copypaste part from another scripts some of them already on this page).
We have build jobs which only build code (job ends with "-build" suffix) and depoy jobs (the same name as build job, but "-CI" suffix).
Task was to determine does code already built (and skip build step which save time and resources because don't need to rerun build job again) otherwise to trigger build job, and then retrieve component version and trigger deployment tool (to pass arguments which WAR to deploy).
build job system groovy script:
deploy job system groovy script:
Unknown User (yamau6809)
Does anyone have a problem specifying classpath for a script using the class path edit box build option targeting Windows?
When I specify multiple jar files in the edit box, the script cannot import a Java class specified with 'import' statement. If I use -cp "jarfile1.jar;jarfile2.jar;jarfile3.jar" in the Groovy Parameters edit box, the script can import the specified class.
So it seems to me that quote around classpath is required on Windows, because using the class path edit box does work on Unices.
Thanks,
Unknown User (roosto)
I had the need to create system groovy script to modify build parameters. I was unable to find a direct answer to my question through googling, so I thought I would deposit my solution here in hopes that it will find another who is in need.
In this case, I have one string type parameter that I want to programmatically alter. I don’t want to monkey with any of the other parameters .
h/t to these two questions, which helped me arrive at my answer:
http://stackoverflow.com/questions/10882515/how-to-retrieve-jenkins-build-parameters-using-the-groovy-api
https://groups.google.com/forum/#\!topic/jenkinsci-users/szhuDfCvpiE
Unknown User (kieranshaw)
I too would love to know how to use the classpath field on the execute system groovy script step. The non-system groovy script will let me use @Grab and do something like this:
@Grab(group='org.codehaus.groovy.modules.http-builder', module='http-builder', version='0.7.2' )
However, the system groovy script, which runs in the Jenkins JRE does not have ivy available to do that. I've heard that you could load the ivy jar into the Jenkins war to make this work, but it isn't a very viable option as you'll need to do it after each upgrade.
I've tried adding something like "/tmp/ivy-2.4.0-rc1.jar" to the classpath field but it doesn't make any difference. Looking through the plugin source code, it seems to apply this variable here in the SystemGroovy.java
So it looks like it is used, but it appears to make no difference as I still get "java.lang.NoClassDefFoundError: org/apache/ivy/Ivy" when running a script with a @Grab
What I'm really looking for is a way of running any arbitrary groovy script (using other libraries), but in the context of the Jenkins master so I can get access to jobs and config.
Any ideas anyone?
Thanks!
Unknown User (mr_dfuse)
I keep running into Caused by: java.lang.ClassNotFoundException: org.codehaus.groovy.tools.GroovyStarter
when executing a Groovy script from a job. When I paste the command from the console into a prompt on the slave, it works fine. As I read on the net this migt be caused by setting GROOVY_HOME, but I don't do that (and setting it doesn't solve it)
Unknown User (mr_dfuse)
Ok I checked the source code, it is a bug. See https://issues.jenkins-ci.org/browse/JENKINS-25275
Unknown User (monique)
It seems the provided example
does not work (anymore) with Jenkins 2.5. On an attempt to execute this code the following message is logged in the Jenkins console log:
I tried to invoke
Then there is no warning message in the log, but the attempt to refer (later in the job definition) the variable in a shell script reveals an empty value, i.e. the variable is not transferred to the build (defined outside the Groovy script)
Is there any workaround for this problem?
Unknown User (cwcam)
The answer to your question is in the error message you posted. This is related to a security update, that by default will block all parameters you create through groovy.
You can pass in these arguments inside the jenkins.xml
Unknown User (srinivas_n4u)
Thanks for the plugin, it is helping us a lot. We have a groovy script which will execute as a post build step(system groovy script) in all our Jenkins jobs(300+). This groovy script requires few additional jar files to be available in classpath. So if we have any change in external jars versions, it is hard for us to configure these jars in all the jobs from plugin configuration. Can we have a option to add classpath jars at global level(manage jenkins) configuration?
Unknown User (tashoyan)
Ho to set JVM heap parameters like Xmx?
Groovy docs suggest only declaring JAVA_OPTS environment variable: JAVA_OPTS="-Xmx..."
But how to set heap size for a groovy script launched by Groovy plugin from Jenkins?
Unknown User (tashoyan)
Experimentally found that a string entered into "Advanced / Java opts" gets propagated via JAVA_OPTS environment variable. So the answer is: put "-Xmx..." to "Advanced / Java opts" in the "Execute Groovy script" build step configuration.
Unknown User (zeeshanhaq)
Is there any example shared that explains how to use classpath with system groovy script?
Unknown User (tashoyan)
How to use this plugin in Pipelines? For example, I want to execute a Groovy script and I want to use some specific Groovy version and to specify some Java opts.