Jenkins Template Plugin and Build Parameters

Stephen Connolly's picture

Jenkins has this incredibly handy feature of parameterized builds. They allow you to tweak the build when it is being triggered.

There are lots of uses for this. One simple and not immediately obvious use I have is to just put a simple road-block on building, to allow the user to confirm the action. I just add an “Are you sure?” parameter and now clicking on “Build now” will ask the user if they are sure:

project release

Now there are other less trivial uses of build parameters. For example you may have a number of test environments and use a Jenkins build job to reset those environments so that e.g. QA can re-verify the installation and upgrade process. You could create a build job for each environment… or you could use a parameterized build

project reset QA test environment

Anyway, you are only restricted by your imagination as to how you can use parameterized builds.

Jenkins Enterprise has this power feature of templates. These basically allow you to write Jenkins plugins without writing Jenkins plugins. There is a class of enhancements to Jenkins that ordinary people want, but which until now have required writing a Jenkins plugin to obtain. We’ve previously run webinars on some of the ways you can use templates, but I realised that there may be some confusion as to how to get templates to play with parameterized builds.

The reason why you might find confusion is that the templates themselves can have attributes.

So you then have:

  • Template attributes that control the configuration of the project
  • Build parameters that tweak that configuration for a specific build

We also will have more fun as template attributes are expanded using the ${…} style expansion in the template transformer and the build parameters are expanded using the ${…} style expansion in the job configuration… yes that is the same style… so we need to remember to escape the build parameter expansion expressions in the template transformer.

Now the easiest way to do this is to start with a job that will be replaced by the template you are creating (in other words just like you want the template to create)

All examples are Hello Worlds! So here we go…

First we add a build parameter:

build parameter

Then we add a build step using the parameter

build parameter

Now we create a template

create template

And then we add the template attributes.

add template attributes

In this case, for simplicity I am dual purposing the “name” attribute as both the job name and the type of announcement. I could just as easily add an attribute to hold the announcement.

Then we use the “Load Prototype Job” feature of the “Groovy template transformation” to load our job as a template. This has the advantage of escaping all the ${…} style expressions in the job configuration for us:

Load Prototype Job

When we click on the “Load” button the “Script” is populated:

Load button the Script

Now all we need to do is change the “Hello” into “${name}”

transformer

Now we can create new “Announcer” jobs, e.g. let’s create one called “Goodbye cruel”

Announcer

We then can save the job. If there were other template attributes they appear on the job configuration screen. As we have gone for the minimal style, i.e. the name configures everything, our job configuration screen is beautifully empty 

 job configuration screen

When we select the “Build now” link we get asked for the parameters to tweak this specific build with:

 job configuration screen

And finally, the console output:

console output

Hopefully this gives you more ideas as to how you can mix and match the feature set of Jenkins!

For anyone who is interested, here is the template transformer script

—Stephen Connolly

CloudBees

www.cloudbees.com


Stephen Connolly has over 20 years experience in software development. He is involved in a number of open source projects, including JenkinsStephen was one of the first non-Sun committers to the Jenkins project and developed the weather icons. Stephen lives in Dublin, Ireland - where the weather icons are particularly useful. Follow Stephen on Twitter and on his blog.