Sometimes, it is useful/necessary to have your builds take several "parameters." Consider the following use case:
- You set up a test job on Hudson, and it accepts a distribution bundle as a parameter and perform tests against it. You want to have developers do local builds and let them submit builds for test execution on Hudson. In such a case, your parameter is a zip file that contains a distribution.
- Your test suite takes so much time to run that in normal execution you can't afford to run the entire test cycle. So you want to control the portion of the test to be executed. In such a case, your parameter is perhaps a string token that indicates that test suite to be run.
The parameter are available as environment parameters. So e.g. a shell ($FOO, %FOO%) or Ant ( ${env.FOO} ) can access these values.
Defining Parameters
First, you need to define parameters for your job by selecting "This build is parameterized", then using the drop-down button to add as many parameters as you need.
There are different parameter types available, and it is extensible, too. The way parameters take effect is also different depending on the parameter type you choose.
String parameter
String parameters are exposed as environment variables of the same name. Therefore, a builder, like Ant and Shell, can use the parameters. Continuing the above example, the following is a simple example:
- Reference parameter by name in builder. I'm using the "env" command to show the variable, followed by an echo statement to demonstrate referencing the value:
- Run build and observe output toward the bottom of the log (some vars removed for security and brevity):
Ant works equally well. In the Properties section of the Ant builder, define a build property like:
Note that because of the case sensitivity difference of environment variables in Windows and Unix, all the environment variables added by parameters are in upper case.
File parameter
File parameter allows a build to accept a file, to be submitted by the user when scheduling a new build. The file will be placed inside the workspace at the known location after the check-out/update is done, so that your build scripts can use this file.
Define Custom Parameter Types
A plugin can define custom parameter types. See ParameterDefinition for the starting point.
Launching a build with parameters
 | Parameters are Case Sensitive!
When passing parameters through the URL, casing is important! For example token=TOKEN&MESSAGE=yo will not work if the job defines the parameter as Message. |
- A build can be started just by accessing
- All parameters need to be properly URL-escaped. To use with wget, quote the URL on the command line too.
- The parameter delay=0sec can be added to start the build immediately.
- To use a Run Parameter, the value should be in the format jobname#buildNumber (eg. "&MyRunParam=foo-job#123")
- If you are using an authorization token to trigger the builds (Job -> Configure -> 'Build Triggers' -> 'Trigger builds remotely (e.g., from scripts)'), you can access:
Note the "\&".
Limitations
Currently the following are the known problems:
- When build triggers are used to start a build, there's no way to pass parameters. This includes SCM polling, downstream builds, and periodic builds. Instead, the specified default values will be used for string, boolean and choice parameters.
Open issues
How can i pass the configured parameter to the maven execution of the build?
E.g. I've got a maven build and a specific profile should be given as a String parameter in the hudson build.
Comments (41)
Aug 19, 2008
Cees Bos says:
How can I trigger a build based on a url? This is the url without a parameter: ...How can I trigger a build based on a url?
This is the url without a parameter: http://localhost/hudson/job/jobname/build?delay=0sec (http://localhost/hudson/job/jobname/build)
Can I add parametername=value? I tried it, but it didn't work. In this example http://localhost/hudson/job/jobname/build?delay=0sec&BAR=FOO\\
Feb 27, 2009
Thomas Guieu says:
It works for me, if you "download" the URL with a WGET-like, don't forget to quo...It works for me, if you "download" the URL with a WGET-like, don't forget to quote this URL.
Sep 15, 2008
Gregoire Henry says:
Windows Users : use my.prop=%BAR% in ant properties as value expansion see...Windows Users : use my.prop=%BAR% in ant properties as value expansion seems to be made by the OS ......
Dec 09, 2008
Stefan Baramov says:
Linux Users: my.prop=$BAR since the same applies for Linux users as well. ...Linux Users:
since the same applies for Linux users as well. Or at least in the 1.262 version.
Sep 17, 2008
Joel F says:
It seems that if a parameter is in a downstream job, the parameter is not set. I...It seems that if a parameter is in a downstream job, the parameter is not set.
It would be useful to pass parameters to downstream jobs, if they share the same named parameters.
Oct 13, 2008
Yoon Kyung Koo says:
I also think so. I need to build each svn branches, and there's no easy way to ...I also think so.
I need to build each svn branches, and there's no easy way to build downstream the branched modules.
Nov 27, 2011
Scott Cameron says:
See the Parameterized Trigger pluginSee the Parameterized Trigger plugin
Sep 18, 2008
Lukas Rytz says:
A question related to the one by Cees Bos: is it possible to specify build param...A question related to the one by Cees Bos: is it possible to specify build parameters when using the "build periodically" feature?
There is no other way to parametrize a build, right?
Jan 07, 2009
Ricardo Oliveira says:
I believe that it would be very useful if the Build Parameters would also work f...I believe that it would be very useful if the Build Parameters would also work for multi-configuration projects.
Feb 10, 2009
Eagle says:
It would be great to be able to add not only parameter name and value but also s...It would be great to be able to add not only parameter name and value but also specify some description as well, so when user click on ''Build Now" button the parameterized page would give more helpful info about required parameters.
Also in my company we are using mostly boolean based parameters, it would be very useful to add one more type of parameters - Boolean (as a checkbox).
Mar 31, 2009
Sathish Sathyan says:
Is there a way where I can pass multiple default values to a single parameter an...Is there a way where I can pass multiple default values to a single parameter and then select the value of the parameter from a dropdown (which has the default values), and then run the build?
Seems to be a nice feature to have
May 18, 2009
Lars Skjærlund says:
Is there a way to access the parameters from the project configuration page? If...Is there a way to access the parameters from the project configuration page?
If I have a parameter called "Release" holding the release number, it might want to create a custom workspace called "C:\Hudson\Release-$Release" - but this doesn't work. It would be nice to have access to the parameters for use in the project configuration as well.
BTW: Checking out "<long path>/release/$Release" from Subversion does work, though - very nice, indeed.
Jul 13, 2009
jvizueta says:
How can these parameters be accessed from groovy? I'm trying to set parameters a...How can these parameters be accessed from groovy? I'm trying to set parameters and use them from this plugin: http://techkriti.wordpress.com/2008/08/30/using-groovy-with-hudson-to-send-rich-text-email/
But I don't get to find the java code in Hudson where it stores a project parameters:
Here is the code where I'm looking: http://kickjava.com/src/hudson/model/AbstractProject.java.htm
Jul 15, 2009
Yun Zhi Lin says:
Is it possible to make these parameter values available in all fields outside of...Is it possible to make these parameter values available in all fields outside of the build step? In a custom parametrized build I would like to specify a particular CVS/SVN TAG to build against or a particular Ant TASK to call, however I can't use Parameters for any of these fields.
The only way would be to call both Ant, CVS/SVN via commandline using Window Batch Command or Execution Shell and passing in the Parameters there. If these Parameters could be recognized in all the standards fields it would be truly awesome. But I guess this is a problem that applies to all Environment Variables in general.
Sep 13, 2009
srinivas M says:
Is there a possibility to populate the choices dynamically in the dropdown ...Is there a possibility to populate the choices dynamically in the dropdown menu of Choice parameter?this will be very helpful for users to select the value for parameter from available options.
Sep 30, 2009
Chris LeCompte says:
I was able to use the parametrized values in the build and SCM setup for a proje...I was able to use the parametrized values in the build and SCM setup for a project using the ${PARAMETER NAME}
syntax. It's not entirely clear from what's stated above as to what/where/how the parameters are valid, only that they are exposed as environment variables but maybe I missed something. I'm a bit new to Hudson...
Oct 07, 2009
Pascal Gelinas says:
It would be great if we could use the parameters anywhere in the project configu...It would be great if we could use the parameters anywhere in the project configuration page. I've tried using them in some report plugins (JUnit, checkstyle and the like) with no luck... I've tried $parameterName, ${parameter name} and ${PARAMETER NAME} and none worked...
Oct 01, 2009
Alexander says:
There is a useful feature in "Trigger builds remotely" section: "Optionally appe...There is a useful feature in "Trigger builds remotely" section: "Optionally append &cause=Cause+Text to provide text that will be included in the recorded build cause."
Unfortunately it does not work with parametrized builds (no build cause is recorded). Could you please fix it? Or is there another way to make some comments [encoded into url] viewable on the page with build details?
Thanks
Oct 02, 2009
Mikael Monroy says:
It doesn't seem to work with Nant The keywords ${PARAMETER NAME} or $ {env.PARA...It doesn't seem to work with Nant The keywords ${PARAMETER NAME} or $ {env.PARAMETER NAME} are not recognizedOct 30, 2009
Shalmali Mahajan says:
The case of the parameter name has to match with that of the declared name every...The case of the parameter name has to match with that of the declared name everywhere where it is accessed.
In Ant, I could access the parameter only when it was not preceded by 'env'.
Nov 11, 2009
nick chang says:
Is there a way to post fileparameters using the buildWithParameters remote trigg...Is there a way to post fileparameters using the buildWithParameters remote trigger path? Whenever I try encoding the parameters using multipart via python ( http://code.activestate.com/recipes/146306/ ), i get internal server errors.
Nov 15, 2009
xu wei says:
I want to setup a staged build, e.g. project-unit, project-integration, project-...I want to setup a staged build, e.g. project-unit, project-integration, project-deploy-QA, project-deploy-staging, project-deploy-production.
I want to make sure the different stage are using the same revision, so can I add a parameter for the revision? the value is dynamicly came from the upstream project.
or is there any other way to help to do that?
thanks
May 11, 2010
Miles D. Duke says:
Have you had any luck setting this up? We are trying something like this also. ...Have you had any luck setting this up?
We are trying something like this also. Suppose, project B depends upon project A. If a new SCM change affects project A, we want A to build at that version. Because other changes may happen while A is building, we want B to build at the same SCM version.
We think a parameterized build might help.
However, we also have the scenario where an SCM change only affects B. In this case, we would like the build on B to start (provided the upstream versions aren't in progress).
Feb 10, 2010
boy.pockets says:
I seem to be getting some inconsistent behaviour (or most likely, I don't unders...I seem to be getting some inconsistent behaviour (or most likely, I don't understand what is happening).
I have a string parameter:
I set the value to:
${Workspace}\${JOB_NAME}\workspace\binWhen I try and use this in a Windows Batch Command like so:
I get this in the Output:
C:\WINDOWS\system32\config\systemprofile\.hudson\jobs\HudsonUtils\workspace>cd ${Workspace}\HudsonUtils\workspace\bin The system cannot find the path specified. :(Note:
${JOB_NAME}is the project specific environment variable
${Workspace}is a Global Property (set in the hudson/configure page)
I am able to access Workspace directly, by using %Workspace% in a Windows batch command. But I would have expected ${JOB_NAME} to fail too if ${Workspace} fails. It seems that Hudson is evaluating the value of ${JOB_NAME}, but not ${Workspace}.Feb 10, 2010
boy.pockets says:
Just a quick note about WORKSPACE and Workspace. They are different variables - ...Just a quick note about WORKSPACE and Workspace. They are different variables - upper case is the project specific variable and Cammel case is the Hudson wide variable (something I added). I tried deleting the one i created, but I still had the same problem with WORKSPACE.
Feb 24, 2010
Erdal Karaca says:
It seems that parameters are not visible to parameters, i.e. I cannot embed decl...It seems that parameters are not visible to parameters, i.e. I cannot embed declared parameters inside other parameters:
my.param=value1
my.other=${my.param}-${JOB_NAME}
The JOB_NAME will be expanded, my.param not. Is this a 'missing feature' or do I miss something?
Apr 09, 2010
Mark Wolff says:
If I want to send multiple parameters, I would say...? http://server/job/myjob/b...If I want to send multiple parameters, I would say...? http://server/job/myjob/buildWithParameters?PARM1=Value1;PARM2=Value2
I've gone through ;, & and a few others. I've looked at examples, URL/DNS standards docs, etc and still no luck. Any help here?
Answer is http://server/job/myjob/buildWithParameters?PARM1=Value1;PARM2=Value2http://server/job/myjob/buildWithParameters?PARM1=Value1&PARM2=Value2
Jun 01, 2010
Pablo Gil says:
How can you do the same for a Maven Release? When I try to perform a Maven Relea...How can you do the same for a Maven Release? When I try to perform a Maven Release on a Parameterized job it does not ask for any parameter...
Jul 22, 2010
Josh Figler says:
I'm trying to figure out how to do the Parameterized Build with a File Parameter...I'm trying to figure out how to do the Parameterized Build with a File Parameter. I understand everything except how to specify the file to be uploaded. Can someone please provide an example?
Jul 28, 2010
Kedar Mhaswade says:
Josh, Does this help? http://infradna.com/content/using-file-parameters-hudson...Josh,
Does this help?
http://infradna.com/content/using-file-parameters-hudson-parameterized-builds
Thanks,
Kedar
Sep 09, 2010
Josh Figler says:
Yes – it does! Thanks!Yes – it does! Thanks!
Aug 04, 2010
Jamie Thomson says:
Hi folks, Day 1 with Hudson ... slowly but surely getting up to speed. My ques...Hi folks,
Day 1 with Hudson ... slowly but surely getting up to speed.
My question is about run parameters. I've seen that I can use them to reference a particular run of a particular project - that's all fine.
What I don't understand (and can't find any docs on) is how I refer to anything in the run defined by the run parameter. Essentially I want to reference the %BUILD_NUMBER% & %SVN_REVISION% of the run that is chosen. How can I do that?
thanks in advance
Jamie Thomson
Nov 16, 2010
Henri Gomez says:
I set a job with parameter. It works well with Hudson used in standalone (ie: To...I set a job with parameter.
It works well with Hudson used in standalone (ie: Tomcat + Hudson webapp).
I notice a 405 HTTP (error) code is sent back to browser when clicking on a job with build parameters.
But operations continue....
Problem appears with a couple like Apache HTTPd and Tomcat 6, and with mod_jk configured to let Apache HTTPd handling errors like 404, 500...
JkUnmount /errors_pages/* hudson;use_server_errors=400 JkMount /* qahudson;use_server_errors=400I had to use the following settings (transforming 404 into 503, a weird hack) and jk won't consider error for HTTP code less than 500.
JkUnmount /errors_pages/* hudson;use_server_errors=500;fail_on_status=-404, JkMount /* hudson;use_server_errors=500;fail_on_status=-404Could you fix the 405 sent back and use a 200 instead ?
Jan 04, 2011
Kendrick Martin says:
What would be the best process for setting up multiple schedules that each pass ...What would be the best process for setting up multiple schedules that each pass in different values for the parameters? Say I have a job that I want to run every 30 minute with a limited test sweet and then once a night I want to call it with the full suite.
Nov 27, 2011
Scott Cameron says:
I have this requirement as well. Looks like the only way is to trigger the build...I have this requirement as well.
Looks like the only way is to trigger the build via cron and pass the parameters that way.
e.g.
http://server/job/myjob/buildWithParameters?PARAMETER=Value
Jan 19, 2011
vladimir knajtner says:
Inability to pass parameters to downstream build is a major flaw. I want t...Inability to pass parameters to downstream build is a major flaw. I want to have a separate generic parametrized build and nightly regression test jobs that can be invoked in an arbitrary sequence.
Nov 27, 2011
Scott Cameron says:
See the Parameterized Trigger pluginSee the Parameterized Trigger plugin
Feb 04, 2011
Brian Stephenson says:
Is there any way to "nest" parameters? I have a choice parameter DEPLOY_TYPE tha...Is there any way to "nest" parameters? I have a choice parameter DEPLOY_TYPE that would be "TEST" or "DEMO" and I have two string parameters: TEST_IP and DEMO_IP, obviously set to the IPs of the two types of servers (test and demo). Is there any way in Hudson that I can do the equivalent of this: "${$[DEPLOY_TYPE]_IP}" (this Wiki won't let me use curly brackets around DEPLOY_TYPE, it tries to interpret it as a Hudson macro, but trust me they are curly), so that I get TEST_IP if I choose TEST and DEMO_IP if I choose DEMO? My only other option is to have the user choose both the deploy type and the target IP, which is less than elegant or ideal. Thanks for any assistance.
Feb 10, 2011
cubeuser says:
Is it possible to pass the environment variable to svn url.? I tried to define ...Is it possible to pass the environment variable to svn url.?
I tried to define a variable named 'BRANCH' and tried to use it in svn url, but it didn't work.
https://<SVN REPO>/branches/$BRANCH
any other suggestions.? thanks!
Nov 30, 2011
Donner Speer says:
Your posts are so helpful and detailed. The links you feature are also very usef...Your posts are so helpful and detailed. The links you feature are also very useful too. Thanks a lot!
elegant wedding dresses
Mar 12, 2012
Alvin Reyes says:
Hello, is it possible to set multiple revision numbers in the paramters? We are ...Hello, is it possible to set multiple revision numbers in the paramters? We are currently doing parallel development on our source code and I need to integrate changes (from different file versions) into the build.
Thanks,