 | This is still a very young feature, so feedback appreciated |
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
To use this properly with wget, you need to quote the URL.
Apparently the parameter delay=0sec can be used.
- 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.
Parameterized Build
Comments (21)
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.
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
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
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
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
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
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
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
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
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
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
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