Parameterized Build

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:

  1. 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:
  2. Run build and observe output toward the bottom of the log (some vars removed for security and brevity):
    started
    [workspace] $ /bin/sh -xe /opt/apache-tomcat-6.0.14/temp/hudson20854.sh
    + env
    BAR=bat
    ...
    [workspace] $ /bin/sh -xe /opt/apache-tomcat-6.0.14/temp/hudson20855.sh
    + echo the value of bar is bat
    the value of bar is bat
    finished: SUCCESS
    

Ant works equally well. In the Properties section of the Ant builder, define a build property like:

my.prop=${env.BAR}

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
http://server/job/myjob/buildWithParameters?PARAMETER=Value
  • 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:
    http://server/job/myjob/buildWithParameters?token=TOKEN\&PARAMETER=Value

    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.

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.
  1. 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\\

    1. 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.

  2. 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 ......

    1. Dec 09, 2008

      Stefan Baramov says:

      Linux Users: my.prop=$BAR since the same applies for Linux users as well. ...

      Linux Users:

      my.prop=$BAR
      

      since the same applies for Linux users as well. Or at least in the 1.262 version.

  3. 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.

    1. 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.

      1. Nov 27, 2011

        Scott Cameron says:

        See the Parameterized Trigger plugin

        See the Parameterized Trigger plugin

  4. 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?

  5. 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.

  6. 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).

  7. 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

  8. 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.

  9. 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

  10. 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.

  11. 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.

  12. 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...

    1. 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...

  13. 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

  14. 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 recognized
    
    1. Oct 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'.

  15. 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.

  16. 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

    1. 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).

  17. 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:

    LocalOutputPath
    

    I set the value to:

    ${Workspace}\${JOB_NAME}\workspace\bin
    

    When I try and use this in a Windows Batch Command like so:

    cd %LocalOutputPath%
    

    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}.
    
    1. 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.

  18. 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?

  19. 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

  20. 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...

  21. 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?

  22. Jul 28, 2010

    Kedar Mhaswade says:

    Josh, Does this help? http://infradna.com/content/using-file-parameters-hudson...
    1. Sep 09, 2010

      Josh Figler says:

      Yes – it does! Thanks!

      Yes – it does! Thanks!

  23. 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

  24. 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=400
    

    I 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=-404
    

    Could you fix the 405 sent back and use a 200 instead ?

  25. 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.

    1. 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

  26. 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.

    1. Nov 27, 2011

      Scott Cameron says:

      See the Parameterized Trigger plugin

      See the Parameterized Trigger plugin

  27. 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.

  28. 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!

  29. 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

  30. 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,