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.

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.

Limitations

Currently the following are the known problems:

• There's no easy way to submit parameters when you are programmatically invoking a build from outside without a browser. (issue #2409)
• 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.