Jenkins Template Plugin and Build Parameters

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:

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

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:

Then we add a build step using the parameter

Now we create a template

And then we add the 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:

When we click on the "Load" button the "Script" is populated:

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

Now we can create new "Announcer" jobs, e.g. let's create one called "Goodbye cruel"

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

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

And finally, the 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
cloudbees.com

Stephen Connolly has over 20 years experience in software development. He is involved in a number of open source projects, including Jenkins . Stephen 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 .