Sometimes, it is useful/necessary to have your builds take several “parameters.” Consider the following use case:

  • You  set up a test job on Jenkins, 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 Jenkins.  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 parameters are available as environment variables. 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.

Jenkins Parameterized Build Uncategorized

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:
Jenkins Parameterized Build Uncategorized

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/jenkins20854.sh 
+ env 
BAR=bat 
... 
[workspace] $ /bin/sh -xe /opt/apache-tomcat-6.0.14/temp/jenkins20855.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.

Maven works fine too, e.g. in the Advanced→Properties section of “Invoke top-level Maven targets":

someProperty=$BAR

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 POSTing to

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%2399” for foo-job #99)

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 that the & will need to be escaped, or the whole URL quoted, if using a Unix shell script.)

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.

,
Show Comments