Hudson-ci/Using Hudson/Parameterized Builds

Hudson Continuous Integration Server
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

	Parameterized Builds using Hudson

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:

1. Run build and observe output toward the bottom of the log (some vars removed for security and brevity):

>nowiki>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 </nowiki>

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

Note that 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 ampersand.