Using Jenkins Templates Plugin to Construct Reusable Jobs and Builders

Written by: Harpreet Singh
4 min read

The Templates plugin (available as part of Jenkins Enterprise by CloudBees) brings meta-programming to Jenkins. There are three ways to think of templates:

  1. Shielding Jenkins configuration generality from end users: In a number of cases, a Jenkins administrator needs users to enter a couple of domain-specific terms, yet not expose the entire job configuration to them.

  2. Capture the sameness of configurations across environments: Useful when organizations have a large number of jobs that differ by only a few things. For example, a job that pulls from a different Git repository branch for every developer.

  3. Writing a plugin without actually programming plugins.

I will talk about [1] and [2] in this blog.

Jenkins Templates plugin
Figure 1: Template Types

The Templates plugin has a notion of re-usable components (just think of them as an equivalent of class, attributes and instance from the object oriented programming paradigm). These components are the building blocks that can be used to build other components or can be (optionally) instantiated themselves. One huge advantage of using the Templates plugin is that if the template definition changes, then it is reflected in all jobs using that template; thus simplifying management of large numbers of jobs.

This blog highlights two components: The Builder and the Job template. Figure 1 shows the different types of templates that can be created with Jenkins Enterprise by CloudBees.

Builder Templates

Jenkins Templates plugin
Figure 1: Template Types

Usually developers end up using shell scripts to address requirements like custom deployments, integration steps, etc. These scripts are added to the build steps of jobs and run as part of the job. The scripts are used across jobs and differ only in attributes. The ideal solution is to capture these scripts into one common definition and apply it across jobs. This is exactly what builders let you do, and they are also the easiest templates to create!. Figure 2 shows how a pre-created builder Wakeup someone shows up in the Add build step of a job configuration. Figure 3 shows the configuration information required for this particular builder.

Jenkins Builder Templates
Figure 2: Adding a build step

By defining this builder, I have captured the sameness of jobs mentioned in [2] above.

Job Templates
Job templates can be thought of as one level of abstraction above builders. Here we templatize the whole job instead of a portion of a job. Figure 4 shows that you can create a new job of type Wakeup Job . Wakeup Job was created through the Job template option shown in Figure 1 .

Jenkins configuring a build step
Figure 3: Configuring a build step

Usually, in an enterprise setting, a number of jobs are built the same way; for example, jobs may differ only by the branch that they are checked out from, or tests may differ by pointing to a different database. A Jenkins administrator would like to expose only this configuration to users and not expose any other details. This way the administrator has greatly simplified configuration for end users and has simplified his administration maintenance as he knows that users will not mis-configure jobs.

Creating a new job type
Figure 4: Creating a new job type

Figure 5 shows the configuration options for Wakeup Job . The end user does not see any other options - the job may be a free style job or a Maven job underneath - the end user does not care.

By defining this template, I have captured the sameness of configuration [2] and shielded users from configuration generality [1].

Thus templates simplify administration overhead and capture best practices within an organization.

There is a simple example on templates that I have written in our wiki that builds an alarm (or a reminder) system for users. The wake up alarm system requirements are that it takes three configuration parameters: Who to wake up? Who is waking them up? And, after how much time should they be woken up?

The example takes a builder template and lets you insert build steps in existing jobs (and in new jobs). The job template creates jobs that display only the configuration information that is required, everything else is hidden from users creating the jobs. Thus, the example solves the issue at both abstraction levels. In fact, the job template ends up using the builder template as a building block.

Templates remind me of a very sharp slogan I had heard years ago: "I'd rather build programs to build programs than build programs." :-)

  • Harpreet Singh, Senior Director Product Management

Stay up to date

We'll never share your email address and you can opt out at any time, we promise.