JenkinsEnterprise UserGuide 1.0 PDF

Jenkins Enterprise
by
CloudBees
User Guide
Copyright ...................................................................................................................... v
1. Introducing Jenkins Enterprise by CloudBees ......................................................... 1
1.1. Introduction .................................................................................................... 1
1.1.1. Large Install Plugins ........................................................................... 1
1.1.2. Optimized Utilization Plugins ............................................................ 1
1.1.3. Security Plugins .................................................................................. 2
2. Backup Plugin .......................................................................................................... 3
2.1. Introduction .................................................................................................... 3
2.2. Taking Backup .............................................................................................. 3
2.3. Configuring Backup ...................................................................................... 3
2.4. Restoring From Backup ................................................................................ 4
3. Even Scheduler Plugin ............................................................................................. 5
3.1. Introduction .................................................................................................... 5
3.1.1. Default Jenkins Behavior ................................................................... 5
3.1.2. Even Loading Strategy ....................................................................... 6
3.2. Using Even Scheduler Plugin ........................................................................ 6
3.2.1. Selecting Global Preference ............................................................... 6
3.2.2. Selecting Per-Job Preference .............................................................. 7
4. Folders Plugin .......................................................................................................... 8
4.1. Introduction .................................................................................................... 8
4.2. Overview ....................................................................................................... 8
4.3. Setting up the Folder plugin .......................................................................... 8
4.4. Using the Folders plugin ............................................................................... 9
4.4.1. A sample taxonomy with the Folders plugin .................................... 10
4.4.2. Using folders with other Jenkins Enterprise plugins ........................ 11
5. Label Throttle Build Plugin ................................................................................... 12
5.1. Introduction .................................................................................................. 12
5.2. Overview ...................................................................................................... 12
5.3. Setting up the Label Throttle Build plugin ................................................. 12
5.3.1. ............................................................................................................ 13
6. Role Based Access Control Plugin ........................................................................ 16
6.1. Introduction .................................................................................................. 16
6.2. Concepts and Definitions ............................................................................ 16
6.3. Setting up the Role Based Access Control plugin ....................................... 17
6.3.1. Enabling the authorization strategy .................................................. 19
6.3.2. Configuring and managing roles ...................................................... 21
6.3.3. Configuring and managing groups ................................................... 24
6.3.4. Configuring and managing role filters .............................................. 29
6.4. Example Configurations .............................................................................. 31
6.4.1. Instance owned by one cross-functional team .................................. 31
6.4.2. Instance shared by multiple cross-functional teams .......................... 33
6.4.3. Instance shared by multiple single-function teams ........................... 35
ii
Jenkins Enterprise by CloudBees User Guide

6.4.4. Secret projects on a shared instance ................................................. 36
6.5. Troubleshooting ........................................................................................... 37
6.5.1. Recovering from a lock-out .............................................................. 37
6.5.2. Completely resetting the configuration ............................................. 39
6.5.3. Finding hidden projects .................................................................... 41
7. Skip Next Build Plugin .......................................................................................... 42
7.1. Introduction .................................................................................................. 42
7.2. Using the Skip Next Build plugin ............................................................... 42
7.3. Advanced usage ........................................................................................... 44
8. Template Plugin ..................................................................................................... 45
8.1. Introduction .................................................................................................. 45
8.2. Tutorial: Hello world builder ...................................................................... 45
8.2.1. Define a template ............................................................................. 45
8.2.2. Use a template .................................................................................. 49
8.2.3. Changing the template definition ..................................................... 49
8.3. Tutorial: job template for Jenkins plugin .................................................... 50
8.3.1. Creating a template ........................................................................... 52
8.3.2. Defining transformation .................................................................... 54
8.3.3. ............................................................................................................ 57
8.4. Concepts ...................................................................................................... 59
8.4.1. Models .............................................................................................. 60
8.4.2. Attributes .......................................................................................... 61
8.5. Attribute Type Reference ............................................................................ 61
8.5.1. Text field .......................................................................................... 61
8.5.2. Text area ........................................................................................... 62
8.5.3. Checkbox .......................................................................................... 62
8.5.4. Nested Auxiliary Models .................................................................. 62
8.5.5. Select a string among many ............................................................. 63
8.5.6. Computed Value ............................................................................... 63
8.5.7. Model Transformer ........................................................................... 64
8.5.8. Heterogeneous components from descriptors ................................... 64
8.5.9. Heterogeneous components from descriptors (one instance per
descriptor) ................................................................................................... 64
8.5.10. Select another model ...................................................................... 64
8.5.11. Select item ...................................................................................... 65
8.6. Builder Template ......................................................................................... 65
8.6.1. Creating a new Builder Template ..................................................... 66
8.6.2. Defining Transformer ....................................................................... 66
8.7. Job Template ............................................................................................... 68
8.7.1. Configuration .................................................................................... 68
8.8. Folders Template ......................................................................................... 69
8.8.1. What a folder template controls and what it doesnt ........................ 70
iii
Jenkins Enterprise by CloudBees User Guide

8.8.2. Folder features that work well with templates ..................................
8.9. Auxiliary Template ......................................................................................
8.9.1. Accessing attributes of auxiliary instances .......................................
8.10. Transformer Reference ..............................................................................
8.10.1. Jelly-based transformation ..............................................................
8.10.2. Groovy template transformation .....................................................
8.11. Advanced Template Techniques ...............................................................
8.11.1. Navigating around objects in context .............................................
9. VMware Pool Auto-Scaling Plugin ........................................................................
9.1. Introduction ..................................................................................................
9.2. Configuration ...............................................................................................
9.2.1. Machine Centers ...............................................................................
9.2.2. Machine Pools ..................................................................................
9.3. Building Jobs on Virtual Machines .............................................................
9.4. Assigning a Virtual Machine to a build ......................................................
10. Wikitext Plugin .....................................................................................................
10.1. Introduction ................................................................................................
10.2. Overview ....................................................................................................
10.2.1. Supported Wiki Markup Languages ...............................................
10.3. Setting up the Wikitext plugin ..................................................................
10.4. Using the Wikitext plugin .........................................................................
Index ...........................................................................................................................
70
71
72
72
72
73
73
73
75
75
75
75
76
78
78
79
79
79
79
80
80
81
iv
Copyright
Copyright 2011 CloudBees, Inc.
Online version published by CloudBees, Inc., Boston, MA., USA.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache
Software Foundation. Used with permission. No endorsement by The Apache Software
Foundation is implied by the use of these marks.
Other names may be trademarks of their respective owners. Many of the designations
used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and CloudBees, Inc. was
aware of a trademark claim, the designations have been printed in caps or initial caps.
While every precaution has been taken in the preparation of this book, the publisher
and authors assume no responsibility for errors or omissions, or for damages resulting
from the use of the information contained herein.
Chapter 1. Introducing Jenkins Enterprise

by CloudBees
1.1. Introduction
Jenkins Enterprise by CloudBees (referred to as Jenkins Enterprise in this guide) is
CloudBees professional version of Jenkins. Jenkins Enterprise provides a number of
plugins that help organizations address three main problem areas, described below.
Additionally, with Jenkins Enterprise, Jenkins users are provided with a stable release
and frequent patches. The current release of Jenkins Enterprise is Jenkins Enterprise
11.11, released in November 2011.
The three main areas that Jenkins Enterprise helps Jenkins users in are:
1.1.1. Large Install Plugins

Jenkins Enterprise helps administrators manage large numbers of jobs, projects and
teams. The plugins that help with large installation problems are:
Folders Plugin
Folders help to create hierarchies or custom taxonomies to better manage large
numbers of jobs
Templates Plugin
Capture sameness of configuration information in one place that is propogated
Backup Scheduling Plugin
Use Jenkins to backup Jenkins. No more cron jobs or error-prone custom scripts.
1.1.2. Optimized Utilization Plugins

Jenkins Enterprise helps administrators make better use of existing resources with the
following plugins:
VMware ESXi/vSphere Auto-Scaling Plugin
Make better use of existing VMWare resources by using machines in VMWare
pools as slaves.
Label Throttle Build Execution Plugin
Define the bare-metal limits for VMs being used as slaves. This helps in faster
runs when multiple builds are running multiple VMs on a single bare-metal
machine.
Even Load Strategy Plugin
1
Introducing Jenkins Enterprise by CloudBees

Change the default slave allocation algorithm of Jenkins to go to allocate jobs to
free machines.
Skip Next Build Plugin
Stop running builds if there are known errors that are being fixed.
1.1.3. Security Plugins

Jenkins Enterprise helps administrators secure their projects and their installations with
the following plugins:
Role-Based Access Control (RBAC) Plugin
Setup sophisticated authorization policies to manage Jenkins
WikiText Descriptions Plugin
Prevent potential XSS attacks due to HTML descriptions in Jenkins
This is a user guide for all the plugins available with Jenkins Enterprise. The plugins
are listed in alphabetical order.
Chapter 2. Backup Plugin

2.1. Introduction
The backup plugin simplifies the execution and the administration of backups. Backing
up Jenkins Enterprise is important for several reasons; for a disaster recovery such as
a disk failure, for retrieving old configuration in case someone accidentally deleted
something important, and for auditing for tracing back the origin of a particular
configuration.
The Backup plugin was introduced in Nectar 10.10 and had upgrades in Nectar 11.10.
2.2. Taking Backup

This plugin lets you create backup jobs as jobs on Jenkins Enterprise. In this way, you
can use the familiar interface for scheduling execution of backup, and monitor any
failure in backup activities.
To create a backup, click "New Job" from the left and select "Backup Jenkins". This
takes you to the page where you configure the backup project. Configuration of a
backup job is very similar to that of a freestyle project. In particular, you can use
arbitrary build triggers to schedule backup. Once the trigger is configured, click "Add
build step" and add "Take backup" builder.
You can add multiple backup build steps to take different subsets of backups at the
same time, or you can create multiple backup jobs to schedule different kind of backup
execution at different interval. For example, you might have a daily job that only
backs up the system configuration and job configuration, as they are small but more
important, then use another job to take the full backup of the system once a week.
2.3. Configuring Backup

The "Take backup" builder consists of three independent configuration aspects.
One is "what to backup", which controls the data included/excluded from the backup.
This plugin classifies data into several different aspects:
System configuration
This includes all the settings scoped to the entire Jenkins Enterprise, such as
everything in the system configuration page, plugin binaries, plugin settings,
user information, fingerprints. Anything that lives outside the individual job
directory.
Job configuration
This includes all the settings scoped to individual jobs. Mostly this maps to the
job configuration.
3
Backup Plugin
Build records
This includes information scoped to individual builds, such as its console output,
artifacts, test reports, code analysis reports, and so on.
The next ons is "where to backup", which controls the destination of the backup.
Local directory
This tells Jenkins Enterprise to backup data as a file in the file system of the
master. For disaster recovery purpose, it is recommended that you back up files
to a network mounted disk.
Remote SFTP server
This tells Jenkins Enterprise to connect to a remote SFTP server and send a
backup over there. This is more convenient way to back up to a remote system
on Unix as it requires no shared file system.
The last one is the retention policy, which controls how many/long backups are kept.
By using this switch you can avoid run-away disk consumption caused by old backups.
Backup retention is based on file names; backup file names include the job name
and the build number of the backup job. So you can safely use a single destination
directory for multiple backup jobs and their backup retention policies are enforced
without interfering with each other.
Exponential decay
This tells Jenkins to keep lots of newer backups and fewer old backups. It's
called "exponential decay" because the number of backups kept is proportional
to e^-t. In this way, you'll always cover the entire lifespan of your Jenkins
installation with some backups, with more coverage on recent data.
Keep all backups
In this mode, Jenkins will not delete any backups that it has created. This is
useful if you are managing backup retention externally, such as via logrotate.
Keep N backups
In this mode, Jenkins will keep the latest N backups and delete any older ones.
2.4. Restoring From Backup

Backup files are in the tar+gzip format, and they can be restored onto Jenkins
by running the tar command. Relative directories inside the archive is rooted at
$JENKINS_HOME, so that's where you want to run the tar command.
is relocatable, meaning you don't have to restore the backup into the
same instance it was created. This allows you to exercise the backup restore steps by
creating a different Jenkins instance on your own computer and restoring things there.
$JENKINS_HOME
Chapter 3. Even Scheduler Plugin

3.1. Introduction
On Jenkins Enterprise by CloudBees/Jenkins with a lot of slave nodes, Jenkins needs
to decide where to run any given build. This is called "scheduling", and there are
several aspects to consider when one thinks of scheduling.
Firstly, there's restricting which subset of nodes can execute any given build. For
example, if your job is to build a Windows installer, chances are it depends on some
tools that are only available on Windows, and therefore you can only execute this
build on Windows nodes. This portion of the scheduling decision is controlled by core
Jenkins.
The second part is determining one node that carries out the build, of all the qualifying
nodes, and this is what this plugin deals with.
3.1.1. Default Jenkins Behavior

To better understand what this plugin does, let us examine the default scheduling
algorithm of Jenkins. How does it choose one node out of all the qualifying nodes?
By default, Jenkins employs the algorithm known as consistent hash algorithm to
make this decision. More specifically, it hashes the name of the node, in numbers
proportional to the number of available executors, then hash the job name to create
a probe point for the consistent hash. More intuitively speaking, Jenkins creates a
priority list for each job that lists up all the slaves in their "preferred" order, then pick
the most preferred available node. This priority list is different from one job to another,
and it is stable, in that adding/removing nodes generally only causes limited changes to
these priority lists.
As a result, from the user's point of view, it looks as if Jenkins tries to always use
the same node for the same job, unless it's not available, in which case it'll build
elsewhere. But as soon as the preferred node is available, the build comes back to it.
This behaviour is based on the assumption that it is preferable to use the same
workspace as much as possible, because SCM updates are more efficient than SCM
checkouts. In a typical continuous integration situation, each build only contains a
limited number of changes, so indeed updates (which only fetches updated files) run
substantially faster than check outs (which re-fetches all the files from scratch.)
This locality is also useful for number of other reasons. For example, on large Jenkins
with lots of jobs, this tends to keep the number of the workspaces on each node small.
Some build tools use local caches (such as maven and rvm), and they work faster if
Jenkins keeps building a job on the same node.
However, the notable downside of this strategy is that when each slave is configured
with multiple executors, it doesn't try to actively create balanced load on nodes. For
5
Even Scheduler Plugin

example, if you have two slaves X and Y, each with 4 executors. If at one point X is
building FOO #1 and Y is completely idle, then on average, the upcoming BAR #1 still
gets assigned to X with 3/7 chance (because X has 3 idle executors and Y has 4 idle
executors.)
3.1.2. Even Loading Strategy

What this plugin offers is a different scheduling algorithm, which we refer to as "even
loading strategy."
Under this strategy, the scheduler prefers idle nodes absolutely over nodes that are
doing something. This in the above example, BAR #1 will always run on Y, because
X is currently building FOO #1. Even though it still has 3 idle executors, it will not be
considered so long as there are other qualifying slaves that are completely idle.
However, idle executors are still idle, so if there are more builds queued up, they
will eventually occupy other 3 executors of X, thereby using this slave to its fullest
capacity. In other words, with this algorithm, the total capacity of the system does not
change it merely changes the order the available capacity gets filled.
The strength of this algorithm is that you are more likely to get a fully idle node. Quite
simply, executing a build on a fully idle system is faster than executing the same
thing on a partially loaded system, if all the other things are equal. However, the catch
is the "if all the other things are equal" part. If the node does not have a workspace
previously checked out, you'll pay the price of fully checking out a new copy, which
can eat away any potential performance gain.
The Even Scheduler plugin was introduced in Nectar 11.10.
3.2. Using Even Scheduler Plugin

This plugin adds two ways to control which algorithm to use for a given job:
Global preference
Picks the scheduling algorithm globally for all the jobs, unless specifically
overridden by individual jobs.
Per-job preference
Picks the scheduling algorithm for a specific job, regardless of the global
preference.
3.2.1. Selecting Global Preference

Go to "Manage Jenkins" and select "System Configuration" to get to the system
configuration page. Then look for "Default Scheduler Preference". Selecting "Prefer
execution on idle nodes over previous used nodes" will make the Even Scheduler
loading strategy the default strategy.
6
Even Scheduler Plugin
3.2.2. Selecting Per-Job Preference

Go to the configuration screen of a job, then select "Override the default scheduler
preference." This will activate the per-job override. If "Prefer execution on idle nodes
over previous used nodes" is selected, it'll tell Jenkins to use the even loading strategy
for this job. Otherwise it'll make Jenkins use the default scheduling algorithm for this
job.
Chapter 4. Folders Plugin

4.1. Introduction
The Folders plugin allows you to organize jobs in hierarchical folders much like how
you organize files in directories in your file system.
4.2. Overview
Jenkins is limited in it's capabilities to organize large number of jobs or organize jobs
around taxonomies such as projects or departments. Today, most teams break up jobs
around views on the dashboard. Views are not optimal to capture custom taxonomies.
The Folders plugin addresses this limitation and helps capture taxonomies in a user
environment and helps organize jobs around these taxonomies.
The Folders plugin allows you to create a folder and group related jobs together.
These jobs can be organized around a project, department, sub-department, release or
any taxonomy that you choose to define. You can create an arbitrary level of nested
folders. Folders are namespace aware, so Job A in Folder A is logically different than
Job A in Folder B
The Folder plugin allows you to clone a folder with its children intact. This is useful
to seed new projects/jobs with information from a particular project type. Folders can
also define properties that are visible to jobs inside, enabling you to simplify branch
and/or workflow managements.
The Folders plugin was introduced in Nectar 11.04.
4.3. Setting up the Folder plugin

The Folders plugin is extremely easy to setup and use. Enable the CloudBees Folder
plugin in the plugin manager as shown in Figure 4.1. Restart Jenkins Enterprise to
enable the plugin.
Folders Plugin
Figure 4.1. Installing the Folders plugin
4.4. Using the Folders plugin

Go to New Job, choose Folder as the job type as in Figure 4.2.
Figure 4.2. Creating a new Folder

The Folders plugin allows you to specify the types of jobs that a particular folder
allows. To choose the specific job types that the folder can allow, enable Restrict the
kind of children in this folder as shown in Figure 4.3.
9
Folders Plugin
Figure 4.3. Specifying parameter types for Folders
Tip
To replicate an existing folder, choose Copy Existing Job and choose the
folder that you want to replicate. This will replicate all jobs and nested
folders.
4.4.1. A sample taxonomy with the Folders plugin

Figure 4.4 shows a potential taxonomy with the folders plugin. In this example, an
organization wants to split its jobs by departments and sub-departments. Here, we have
created a folder called "Department A" with a sub-folder for a sub-department. "A
very important job" that cross cuts across sub-departments sits at the top level in the
department.
Figure 4.4. Sample Taxonomy with Folders plugin

10
Folders Plugin
4.4.2. Using folders with other Jenkins Enterprise plugins

The power of Folders plugin is unleashed with other Jenkins Enterprise plugins.
You can use Folders with the Role-based Access plugin to enable folder-level security
roles. By default, the roles are inherited by sub-folders.
Tip
You can use the filter mechanism with the RBAC plugin to filter out
permissions for a particular sub-folder such that it does not inherit the
parent folder roles.
You can use Folders with the VMWare Pool plugin to localize sharing of pools of
machines to a particular folder.
Tip
This is useful, if you want a particular department or project to share a
particular set of machines
11
Chapter 5. Label Throttle Build Plugin

5.1. Introduction
The Label Throttle Build plugin brings in hypervisor-aware scheduling to Jenkins.
The plugin allows users to limit number of builds on over-subscribed VM guests on a
particular host.
5.2. Overview
In the scenario where slaves are setup as virtual machines and share the same physical
resources underneath, Jenkins may think that there is more capacity for builds than
available.
For example, in such an environment, Jenkins might think that there are 10 slaves with
2 executors each, but in reality the physical machine cannot execute 20 concurrent
builds. The number is usually much lower say, 4 1. This is particularly the case when
you have a single-system hypervisor, such as VMWare ESXi, VirtualBox, etc.
Everytime a new build is to start, Jenkins schedules it to one of the available virtual
slaves. However, in this particular case the underlying physical infrastructure cannot
support all the virtual slaves running their respective builds concurrently.
Jenkins Enterprise allows you to define an actual limit to the number of concurrent
builds that can be run on the system. One can group slaves together, then assign a limit
that specifies how many concurrent builds can happen on all the slaves that belong to
that group. In this way, Jenkins Enterprise avoids overloading your hypervisor host
machine 2.
The benefit of using this plugin is that builds run much faster as the underlying
physical machines are not overloaded anymore.
The Label Throttle plugin was introduced in Nectar 11.04.
5.3. Setting up the Label Throttle Build plugin

Enable the CloudBees Label Throttle Build plugin in the plugin manager as shown in
Figure 5.1. Restart Jenkins Enterprise to enable the plugin.
This number is dependent on user specific configurations.

This is very handy in combination with Jenkins Enterprise VMWare auto-scaling feature.
12
Label Throttle Build Plugin
Figure 5.1. Install from the plugin manager

First, decide a label and assign it to all the slaves that you'd like to group together.
For example, you can use the hypervisor host name as a label, and put that label on all
the slaves that are the virtual machines on that host. This can be done from the slave
configuration page as shown in Figure 5.2
Figure 5.2. Setup appropriate label on the slave configuration page

Then click the newly entered label to jump to the label page as show in Figure 5.2
13
Figure 5.3. Go to the labels page

Then configure this label and enter the limit as shown in Figure 5.4
14
Figure 5.4. Set limit on the hypervisor

With this setting, as you can see, the total number of concurrent builds on hypervisor1
is limited up to 2, and Jenkins Enterprise would enforce this as you can see in the
executor state in Figure 5.5 Two builds are already running, so the third job sits in the
queue.
Figure 5.5. Label throttle build plugin in action
15
Chapter 6. Role Based Access Control

Plugin
6.1. Introduction
The Role Based Access Control plugin gives a Jenkins administrator the ability to
define various security roles that will apply to the system they administer. Once roles
have been defined the Jenkins administrator can assign those roles to groups of users.
The assignment of roles can take place either at the global level, or limited to specific
objects within the system. And, additionally, the Jenkins administrator can even
delegate the management of groups for specific objects to specific users.
The Role Based Access Control plugin combines with the Folders plugin to give
a powerful solution for managing a Jenkins which is shared by multiple teams of
users. The Jenkins administrator can create folders for each of the teams and then
create groups in those folders for each of the roles that team members can have. By
delegating the management of the group membership (but not the management of the
roles assigned to groups) to the team leaders, the Jenkins administrator can empower
the team leads to manage the permissions of their team while reducing their own
administrative overhead.
The RBAC plugin was introduced in Nectar 11.04.
6.2. Concepts and Definitions

The Role Based Access Control plugin introduces a number of new concepts to
Jenkins when enabled. As these concepts and terms are used in a lot of different
systems other than Jenksin, this section defines their meaning within the Role Based
Access Control plugin.
Permission
A Permission is the basic unit upon which roles are built. There is a core
fixed set of permissions defined by Jenkins, but any plugin has the ability to
define additional permissions. If an action within Jenkins requires a specific
permission, then the user wishing to perform that action must have the required
permission.
Security Realm
The Security Realm is responsible for establishing the identity of the user
and reporting what external groups they are members of. Jenkins ships with a
number of security realm implementations and plugins can define additional
16
Role Based Access Control Plugin

security realm implementations. Only one security realm can be active at any
one time.
Authorization Strategy
The Authorization Strategy is responsible for determining what permissions
users have on various objects within Jenkins. Jenkins ships with a number
of authorization strategy implementations and plugins can define additional
authorization strategy implementations. The Role Based Access Control plugin
is an Authorization Strategy. Only one authorization strategy can be active at
any one time.
External Group
An External Group is a group of users which is defined outside of the control of
Jenkins. For example when the LDAP security realm is used, the LDAP groups
that a user is a member of are considered as external groups by the Role Based
Access Control plugin.
Group
A Group (sometimes known as a Local Group), is a group of users, groups
and/or external groups which has been defined within Jenkins and where the
membership of the group is managed by Jenkins. The Role Based Access
Control plugin provides the ability to define and manage groups which are local
to Jenkins. Groups can be defined either at the root of Jenkins, or within specific
objects within Jenkins. When a group is defined within a specific object, that
group is local to the object and the object's child objects.
Role
A Role is a set of permissions that can be assigned to a local group. A user's
effective permissions are the aggregate of all the roles assigned to the groups
they are members of which are within the scope of the object they wish to
perform an action on.
Role Filter
A Role Filter is defined on objects within Jenkins, and allows the restriction of
roles from propagating through from the parents of the object. For example, if
a specific job is to be hidden from all but a small team of users, a group would
be created in that job with the required roles assigned to that group. A role filter
would then be applied to the job to remove all roles from propagating through
from the parent.
6.3. Setting up the Role Based Access Control plugin

Before configuring the Role Based Access Control plugin, it is helpful to review the
checklist in Table 6.1, Pre-configuration checklist
17

Table 6.1. Pre-configuration checklist
Check
Done
Have you got a list of roles do you want to define?
Yes / No
It is usually best to start small, you can always add more later. If
unsure a reasonable minimal set could be: Read-only; Developer;
Manager; and Administrator. Additionally it is helpful to think about
what you want those roles to be able to do.
Have you got a list of groups you want to define?
Yes / No
You will typically require at least one local group for each role you
define. If some roles are only being assigned to specific users or
groups of users on specific objects, then each of those assignments
will require a group local to that object.
Have you configured and tested your security realm?
Yes / No
The first time you enable the Role Based Access Control plugin, it
defaults to a configuration whereby logged in users can do anything
and users cannot access the system anonymously. If you have not
tested that you can successfully log in to the system with the security
realm you are using, enabling the Role Based Access Control plugin
may result in everyone being completely locked out of the system.
See Section 6.5 for details on how to restore access to the system in
the event of a lock-out.
Does your security realm provide details of external groups?
Yes / No
If the security realm does not provide details of external groups

then you (or somebody you delegate the permissions to) may have
to manually maintain synchronization between the external group
membership and any corresponding shadow local groups that you
may define within Jenkins.
Is this the first time the Role Based Access Control plugin will be
enabled?
Yes / No
The Role Based Access Control plugin remembers its configuration

even when a different authorization strategy is configured, this
allows easier experimentation with the plugin, but a side-effect is
that you may have to remove the existing configuration if you want
to start from a clean slate. See Section 6.5 for details on how to
remove any existing configuration.
Are there specific objects which require different permissions?
Yes / No
If most of your jobs will have a permissive set of permissions, but

a few jobs will have permissions restricted to specific users, then
18

Check
the typical design is to grant the permissive permissions at the
root level, filter those permissions out on the few jobs that have
restricted permissions, and define groups for the users who require
permissions on the restricted jobs.
Done
6.3.1. Enabling the authorization strategy

The Role Based Access Control authorization strategy is enabled from the main
configure screen by selecting the Role-based matrix authorization strategy from the
Authorization selections (that are displayed when the Enable Security checkbox is
enabled) and then saving the configuration. See Figure 6.1
Note
The first time you enable the Role Based Access Control plugin, it defaults
to a configuration whereby logged in users can do anything and users
cannot access the system anonymously. If you have not tested that you can
successfully log in to the system with the security realm you are using,
enabling the Role Based Access Control plugin may result in everyone
being completely locked out of the system. See Section 6.5 for details on
how to restore access to the system in the event of a lock-out.
Figure 6.1. Enabling the Role Based Access Control authorization strategy
When the Role Based Access Control authorization strategy is enabled there will be a
number of changes to the Jenkins interface.
19

There will be additional icons for Groups and Roles at the root of Jenkins as well
as on any objects which support the definition of local groups. See Figure 6.2
There will be an additional Manage Roles icon on the Manage Jenkins screen. See
Figure 6.3
Figure 6.2. The main Jenkins screen with the additional icons for Groups and
Roles.
Figure 6.3. The Manage Roles action from the main Manage Jenkins screen.
20
6.3.2. Configuring and managing roles

Roles are configured and managed from the Manage Roles screen accessed via the
Manage Jenkins screen (See Figure 6.3). The first time the Role Based Access Control
authorization strategy is enabled the Manage Roles screen should look something like
Figure 6.4. The screen consists of a table of check boxes with each row of the table
corresponds to a role, and each column corresponding to a permission. By checking the
boxes you can assign permissions to roles.
Figure 6.4. The Manage Roles screen after the Role Based Access Control
authorization strategy has been initially enabled.
There are two types of roles:
system role.
user defined role.
System roles cannot be removed. There are two system roles:
anonymous
This role is automatically assigned to any user that is not logged in. If you do
not want anonymous users to be able to access the system then do not assign any
permissions to the anonymous role.
authenticated
This role is automatically assigned to any user that is logged in. If you want
very fine grained control over user permissions you may end up removing all
permissions from this role.
21

To define a new role you type the name of the role you want to define into the Role
add text box ( Figure 6.5).
to
Figure 6.5. Adding a role called Administrator

Once you have typed the name in click the Add button. This will add a new row to the
bottom of the table ( Figure 6.6).
Figure 6.6. After clicking the Add button in Figure 6.5

Once you have created the row for the new role, you can assign permissions for that
role by clicking the appropriate check boxes.
22
Note
If you want to assign all permissions there is a Check all button at the
far right of the screen. There is also a Clear all button to speed up
clearing all the check boxes in a specific row. See Figure 6.7 and Figure 6.8
Figure 6.7. The three icons for: checking all the check boxes in a row; clearing all
the check boxes in a row; and removing the role.
Figure 6.8. After clicking on the Check

Figure 6.6
all
icon for the Administrator role from

23

If you need to delete a role, there is a
of the user defined roles.
remove button at the far right of the row for all
Once you have defined all the roles you require, you can save that configuration by
clicking on the Save button.
Warning
Care should be taken when removing the Overall Administer permission,
from roles, as it is possible to lock yourself out of administrative access.
There are some safeguards which will protect you from obvious ways of
locking out administrative access, however, as you may legitimately want
to remove your own administrative access, the safeguards can only protect
the obvious issues. See Section 6.5 for details on how to restore access to
the system in the event of a lock-out.
6.3.3. Configuring and managing groups

Groups can be defined at any point in Jenkins where the groups action is available.
The following classes of objects support group definitions out of the box:
Jenkins itself
Jobs
Maven modules in a Maven project
Slaves
Views
Folders
Note
Other objects added by plugins can support group definitions if the required
support is built into the plugin itself, or is added by an additional plugin.
However, in general, the objects need to have been designed to allow other
plugins to contribute actions in order for the group definition support to be
possible.
Where an object does not support group definitions, the groups are inherited
from the object's parent
Clicking on the
Figure 6.9
groups action will bring you to a screen similar to that shown in

24
Figure 6.9. The initial groups screen for the root of a Jenkins instance
You create a group using the New Group action which will prompt for the group
name as in Figure 6.10. Groups can be renamed after they are created. Group names
are case sensitive and whitespace is allowed (although it can be confusing). When a
group is created with the same name as a group from the parent context, it will hide
the group from the parent context, however the permissions granted to members of the
group will not be removed.
Figure 6.10. Creating a new group

25

After the group has been created, depending on the effective permissions of the
user creating the group, one of two screens will be displayed. Users with the Group
Configure permission will be show the Configuration screen ( Figure 6.11), otherwise
the user will be taken straight to the group details screen ( Figure 6.12). This
differentiation is key to effectively allowing administrators to delegate some of the
administrative responsibility.
Figure 6.11. Configuring a group

The Configuration screen is the screen where roles are assigned to a group. By
restricting access to this screen, an administrator can ensure that groups cannot
be created with permissions greater than those intended by the administrator. The
Group Manage permission can then be assigned to specific users in order to allow
them to manage the membership of groups without risking them escalating their own
permissions by the addition of extra roles to groups they belong to.
Where a role is granted to a group, the role can be granted in one of two modes. Be
default the role is granted in the Propagates mode. This means that the role will be
available in child contexts. By clearing the Propagates checkbox, you can create a
pinned role ( ) that is only available on the specific object that the group is created
on. Some examples where a pinned role can be useful would be:
A pinned group creation role at the root allows creating groups at the root while
preventing creating groups on jobs.
A pinned role in a Maven Project job which allows building the job in order to
prevent users from triggering builds of individual modules within the Maven
Project job.
26

When using the Folders plugin, a pinned group creation role on a folder allows
creating groups at the in the folder while preventing creating groups on subfolders.
After the configuration has been saved, the user will be taken to the group details
screen ( Figure 6.12).
Figure 6.12. Managing a group

The Add user/group action is used to add a member to the group. After clicking the
action you will be prompted to enter the id of the user/group to add ( Figure 6.12).
Figure 6.13. Adding a member to a group

27

The ID that you enter can be any of:
A user id
A group name from the current context
A group name from any of the parent contexts
An external group id from the security realm
You can add as many members as you like. Figure 6.14 shows a group containing three
members, one of each type. Circular membership is permitted, i.e. a group can have
as a member a group that it is a member of. When adding external groups the http://
Jenkins-URL /whoAmI page can be useful to figure out what the external group IDs
actually are.
Figure 6.14. A group with multiple members: another group; an external group;
and a user
Members of a group can be removed by clicking on the member's remove icon.

There is a two step confirmation for removing a member and you must confirm the
removal by clicking on the confirmation icon. ( Figure 6.15)
28
Figure 6.15. Removing a member from a group requires two step confirmation
6.3.4. Configuring and managing role filters

Role filters can be defined at any point in Jenkins where group definitions are
supported and roles are inherited from a parent of that object. By default the following
objects will support role filtering:
Jobs
Maven modules in a Maven project
Slaves
Views
Folders
Clicking on the
Figure 6.16.
roles action will bring you to a screen similar to that shown in
29
Figure 6.16. The roles screen for a job within a Jenkins showing the roles, their
permissions, and the groups that are assigned to each of the roles for this object
and its children.
If the object supports role filters then the Filter action will be available from that
screen. Clicking on the Filter icon will bring you to a screen similar to that shown in
Figure 6.17
Figure 6.17. The role filter screen for a job within a Jenkins instance where two
roles are being filtered out
30

To filter a role, you just check the corresponding check-box. When a role is filtered,
then the role is not available on that object to users unless there is a group defined
within that object which the user is a member of and which has been assigned that role.
6.4. Example Configurations

This section details some solutions to common configuration requirements. There are
other ways to solve these configuration requirements, and there is no one correct
solution for any of these, so it is better to think of these as examples of what can be
done.
6.4.1. Instance owned by one cross-functional team

Background.
This example considers the case where there is one team of users
owning the single instance. The team consists of multiple people with different roles.
The most common roles in this case are:
Developer - will want to be able to kick off builds and modify job configuration
Tester - will want to be able to kick off builds, access build artifacts and create
SCM tags
Manager - will want to be able to manage user roles in the team and create
projects
Admin - will want to be able to administer the system
Read only - will require read access to the system but not be able to download
build artifacts
Sample solution.
Create one role for each role of user: developer_role, tester_role,
manager_role, admin_role, and reader_role. Additionally, create one group at the root
level for each role of user, assigning the corresponding role to each group: developers,
testers, managers, admins and readers. Finally add the members to each group as
necessary.
Table 6.2. Sample roles for an instance owned by one cross-functional team
Role
developer_role
Permissions
Job | Configure
Job | Build
tester_role
Job | Build
Job | Workspace
31

Role
manager_role
Permissions
SCM | Tag
Job | Create
Job | Delete
View | Create
View | Delete
View | Configure
Group | Manage
admin_role
Overall | Administer
reader_role
Overall | Read
Job | Read
Group | View
Role | View
Table 6.3. Sample groups for an instance owned by one cross-functional team
Context
Group
Role(s)
Member(s)
ROOT
developers
developer_role
All the developers
ROOT
testers
tester_role
All the testers
ROOT
managers
manager_role
All the manager(s)
ROOT
admins
admin_role
All the administrator(s)

of the instance
ROOT
readers
reader_role
Group: developers
Group: testers
Group: managers
Group: admins
All the people
requiring read-only
access not covered
by the above groups
32
6.4.2. Instance shared by multiple cross-functional teams

Background.
This example considers the case where there are multiple teams of
users sharing the single instance. Each team consists of multiple people with different
roles. The most common roles in this case are:
Build Manager - will want to be create, modify and delete job configurations
Developer - will want to be able to kick off their builds
Tester - will want to be able to kick off their builds, access build artifacts and
create SCM tags
Manager - will want to be able to manage user roles in their teams
Admin - will want to be able to administer the system
Read only - any authenticated user will require read access to the system but not
be able to download build artifacts
Sample solution.
Create one role for each role of user: builder_role, developer_role, tester_role,
manager_role, admin_role, and reader_role. Additionally, create two groups at the
root level for the administrators and readers, assigning the corresponding role to each
group: admins and readers respectively. Use the folders plugin to create folders for the
two teams, and in each folder create groups for the builders, developers, testers and
managers of the respective teams. Finally add the members to each group as necessary.
Table 6.4. Sample roles for an instance shared by multiple cross-functional teams
Role
builder_role
Permissions
Job | Create
Job | Delete
Job | Configure
Job | Build
Job | Workspace
developer_role
Job | Build
tester_role
Job | Build
Job | Workspace
33

Role
manager_role
Permissions
SCM | Tag
Job | Create
Job | Delete
View | Create
View | Delete
View | Configure
Group | Manage
admin_role
Overall | Administer
reader_role
Overall | Read
Job | Read
Group | View
Role | View
Table 6.5. Sample groups for an instance shared by multiple cross-functional

teams
Context
Group
Role(s)
Member(s)
ROOT
admins
admin_role
All the administrator(s)

of the instance
ROOT
readers
reader_role
System identity:
authenticated
Team 1 Folder
builders
builder_role
All the build managers

in team 1
Team 1 Folder
developers
developer_role
All the developers in

team 1
Team 1 Folder
testers
tester_role
All the testers in team 1
Team 1 Folder
managers
manager_role
All the manager(s) of

team 1
Team 2 Folder
builders
builder_role
All the build managers

in team 2
Team 2 Folder
developers
developer_role
All the developers in

team 2
34

Context
Group
Role(s)
Member(s)
Team 2 Folder
testers
tester_role
All the testers in team 2
Team 2 Folder
managers
manager_role
All the manager(s) of

team 2
6.4.3. Instance shared by multiple single-function teams

Background.
This example considers the case where there are multiple teams of
users sharing the single instance. Each team consists of multiple people with the same
role. The most common teams in this case are:
Development - responsible for developing a single product
SQA - responsible for testing many products
DevOps - responsible for deploying many products into production
Sample solution.
Create one role for each role of user: developer_role, sqa_role,
devops_role. Then create groups for the sqa and devops teams at the root level
assigning the corresponding role to each group: sqa, devops. Use the folders plugin
to create folders for each product and within each folder create a developers group
assigned the developer_role. Complete the configuration by adding the members of
each team as members of the corresponding groups.
Table 6.6. Sample roles for an instance shared shared by multiple single-function
teams
Role
developer_role
Permissions
Job | Create
Job | Delete
Job | Configure
Job | Build
Job | Workspace
tester_role
Job | Build
Job | Workspace
SCM | Tag
devops_role
Job | Configure
35

Role
Permissions
Job | Build
Job | Workspace
SCM | Tag
Table 6.7. Sample groups for an instance shared shared by multiple singlefunction teams
Context
Group
Role(s)
Member(s)
ROOT
sqa
sqa_role
All the people in the

SQA team
ROOT
devops
devops_role
All the people in the

DevOps team
Product 1
Folder
developers
developer_role
All the developers of

product 1
Product 2
Folder
developers
developer_role
All the developers of

product 2
6.4.4. Secret projects on a shared instance

Background.
This example considers the case where you want to have a secret
project on a shared instance. The project will be worked on by a small team who
should be able to see the project, but everyone outside of that team will be unable to
see the project.
Note
If somebody has access to the JENKINS_HOME directory, they will be able
to see the secret project. Similarly, by creating an appropriate build script,
a non-secret project could gain access to the secret project when building
on a file system that the secret project has also built on. If it is absolutely
critical that the project remain secret, then it may be best to use a dedicated
instance for the project.
For most use cases, however, the project is being kept secret from people
who both do not have direct access to the JENKINS_HOME directory, and do
not have access to creating build jobs or modify the source code.
Sample solution.
Create a group in the project (or folder) for the team of people
who will be working on the secret project. Add all the roles that the team will require.
Add all the members of the team. Modify the role filters for the project (or folder)
36

filtering out every role (or all but the administrator role if administrators are to be
allowed to view the project).
Note
If you are configuring a secret project to which you will not have access,
once you apply the role filters you will be locked out from the project, and
it will appear as if there is no such project. See Section 6.5.3 for details on
how to recover from accidental lock-outs of this type.
It may also be advisable to create a group for admins of the secret project
before configuring the role filters if only a subset of those with the overall
administrator role are to be able to see the secret project.
6.5. Troubleshooting
6.5.1. Recovering from a lock-out
There are two ways to recover from a lock-out. Both require that the Jenkins instance
be stopped and then restarted after completion of the steps.
The first way will remove all the roles that are defined in the system but does not
require any manual editing of XML files
Procedure 6.1. Recovering from a lock-out by removing all roles (on unix based
systems)
1.
Ensure that the jenkins instance is stopped.
2.
Open a shell
3.
Change into the JENKINS_HOME directory

$
cd
$JENKINS_HOME
4.
Remove/rename the nectar-rbac.xml configuration file

$
mv
nectar-rbac.xml nectar-rbac.xml.old
5.
Start the the jenkins instance.

37

Procedure 6.2. Recovering from a lock-out by removing all roles (on Windows
based systems)
1.
2.
Open a command prompt
3.
Change into the JENKINS_HOME directory

C:\>
cd
%JENKINS_HOME%
4.
Remove/rename the nectar-rbac.xml configuration file

C:\...\Jenkins>
ren
nectar-rbac.xml nectar-rbac.xml.old
5.
The second way will not remove any of the the roles that are defined in the system but
requires manual editing of an XML file.
Procedure 6.3. Recovering from a lock-out by manually editing JENKINS_HOME/
nectar-rbac.xml
1.
2.
Open the JENKINS_HOME/nectar-rbac.xml in a text editor that can edit XML

files
It is a good idea to make a backup copy of the file before changing it.
The file should look something like Example 6.1
3.
Add the following line into the role that you want to have the overall
Administrator permission
<permission id="hudson.model.Hudson.Administer"/>
4.
Save the file
5.

38

Example 6.1. General structure of the nectar-rbac.xml file
<?xml version='1.0' encoding='UTF-8'?>
<nectar.plugins.rbac.strategy.RoleMatrixAuthorizationPlugin>
<configuration class="...">
...
<role name="...">
<permission id="..."/>
...
</role>
...
<role name="anonymous">
...
</role>
<role name="authenticated">
...
</role>
...
</configuration>
</nectar.plugins.rbac.strategy.RoleMatrixAuthorizationPlugin>
6.5.2. Completely resetting the configuration

If you want to completely reset all of the Role Based Access Control plugin's
configuration, an irreversible action, you can use the script console to remove all of the
user defined roles, local groups and role filters on all the objects within your Jenkins
instance.
Warning
There is no way to recover the the user defined roles, local groups and
role filters once you have reset the configuration other than by restoring
a backup of the complete system, and this may have the side-effect of
removing any changes that occur within the system after the configuration
has been reset.
Only follow this procedure if you are absolutely sure that you want to wipe
all of the Role Based Access Control plugin's configuration
Procedure 6.4. Completely resetting the Role Based Access Control plugin's
configuration
1.
If you have been locked out of the system, you will need to follow one of the
procedures in Section 6.5.1 to recover administrative access.
2.
Login to Jenkins using a web browser and open the Script

the Manage Jenkins screen.
Console
from
39

3.
Type the following into the script text box:

nectar.plugins.rbac.strategy.RoleMatrixAuthorizationPlugin
.getInstance().reset()
You should have a screen that looks like Figure 6.18

4.
Click on the Run button. The screen should now look like Figure 6.19
Figure 6.18. Using the script console to completely reset the Role Based Access
Control plugin's configuration.
40
Figure 6.19. After successfully resetting the Role Based Access Control plugin's
configuration via the script console.
6.5.3. Finding hidden projects

You can remove permissions for a project by filtering out roles on that project using a
role filter. In general it is best to add groups and roles to a project before applying the
role filter, as if you filter all roles, you will be locked out from accessing the project
completely. The strategy of filtering out all roles can be used to create secret projects,
however, they can be times when it is necessary to recover/discover the projects that
are hidden.
There are two techniques to discover the hidden projects:
You can reset the configuration using the technique described in Section 6.5.2.
This is somewhat drastic as it allows any authenticated user to see the hiddnen
projects and therefore it is usually not recommended.
Create a new role with all permissions and assign that role to yourself. This works
because the role filters are not updated when a new role is created, and so the new
role's permissions can propagate through. This is the generally recommended
technique as it allows the administrator to prevent hidden projects from becoming
visible to anyone other than the administrator.
41
Chapter 7. Skip Next Build Plugin

7.1. Introduction
The Skip Next Build plugin allows you to skip building a project for a short period
of time. While you could achieve something similar by disabling the project from the
project configure page, however, you would need to remember to re-enable the project
afterwards.
There are two main use cases for this plugin:
If you are going to be taking some external resources that the build requires offline for maintenance and you don't want to be annoyed by all the build failure
notices.
If you are merging a major feature branch and you want to prevent builds until
after the merge is completed.
The Skip Next Build plugin was introduced in Nectar 11.10.
7.2. Using the Skip Next Build plugin

The plugin adds a Skip builds action to all projects. When a skip has been applied to
the project, the icon will be yellow and the main project page will look something
like Figure 7.1. When no skip has been applied the icon will be green
Figure 7.1. The main project screen when a skip has been applied
42

To apply a skip to a project, click on the
screen similar to Figure 7.2.
Skip builds action. This should display a
Figure 7.2. Applying a skip to a project

Select the duration of skip to apply and click the Apply skip button. The main project
screen should now have a notice that builds are skipped until the specified time (See
Figure 7.1 for an example)
To remove a skip from a project, click on the
a screen similar to Figure 7.3.
Skip builds action. This should display
Figure 7.3. Removing a skip from a project

43

Click on the Remove skip button to remove the skip.
7.3. Advanced usage

The Skip Next Build plugin adds two new permissions:
Skip: Apply - this permission is required in order to apply a skip to a project. It is
implied by the Overall: Administer permission.
Skip: Remove - this permission is required in order to remove a skip from a
project. It is implied by the Overall: Administer permission.
The Skip Next Build plugin adds two new CLI operations:
applySkip
- this operation applies a skip to a project. It takes a single parameter

which is the number of hours to skip the project for. If the parameter is outside the
range 0 to 24 it will be brought to the nearest value within that range.
removeSkip
- this operation removes any skip that may have been applied to a
project.
44
Chapter 8. Template Plugin

8.1. Introduction
The template plugin gives the Jenkins administrator the opportunity to provide users
a simplified and directed experience for configuring jobs, in domain specific terms
that makes sense to your organization. With plain-vanilla Jenkins, users can get
confused with a large number of advanced options and switches that they dont need,
resulting in less than optimal user experience and mis-configured jobs. The template
plugin is useful in situations like this, as it allows the administrator to define a few
parameters that users need to fill in, then the administrator would control precisely how
it maps to the fully general configuration, in one place. In this way, most users of your
organization will be shielded from the full generality of Jenkins, and the administrator
will be able to enforce the consistency, best practices, and enterprise rules without an
overhead.
Another typical use case of the template plugin is when you have a large number of
similar looking jobs that only differ in few things, such as jobs building different
branches of the same product, teams building a large number of components in an
uniform way. When you change a template, all the uses of the template gets updated
instantaneously, so the administrator doesnt have to manually update a large set
of jobs to fix a shell script, nor does he need to rely on techniques like the Groovy
console for bulk update.
Yet another way to think of the template plugin is that its like writing a plugin
without writing a program. If you think about the Ant plugin, it lets you configure Ant
invocation with a number of text fields that talk in the domain specific terms of Ant
(such as targets, properties, VM options, etc), as opposed to the single text area that
is the shell script. Or with the maven plugin, you get a whole project type specifically
for invoking Maven, instead of using the generic free-style project and invoke Maven
from it. With the template plugin, you can do these things without actually writing
code.
The template plugin was introduced in Nectar 11.10.
8.2. Tutorial: Hello world builder

Before we dive into gory details, lets create and use a simple template as its an easier
way to wrap your head around the concept of templates. In this tutorial, well create a
template build step that says hello.
8.2.1. Define a template

Once you activate this plugin, youll see the templates link in the top page as
depicted in Figure 8.1.
45
Template Plugin
Figure 8.1. Templates in Jenkins UI

Clicking this link will take you to the list of templates where you can create/update/
delete template definitions. We want to create a new template, so we click New
Template.
Here, we get presented with the choice of the type of the template to create. We want
to create a template that we can use as a builder, which is the likes of execute shell
script, execute windows batch file, invoke Ant, that you can use in configuring
free-style projects. So we choose builder template.
46
Template Plugin
Figure 8.2. Creating a new builder template

The name you enter here will be used to designate this template when someone is
configuring a free-style project, so you better choose something human readable. You
can use any character here (internally each template gets UUID to identify it, so you
dont need to worry about using unsafe characters like space, punctuation, and other
non-ASCII characters, and you can change the name later without breaking anything.)
In this tutorial, we name it Say Hello World, and click OK.
The next page that appears is the configuration page of this template. There are two
main things to configure here: attributes and a transformer.
When you define a template, you first ask yourself what do I want my users to enter
when they use my template? The answer to that question becomes attributes. In this
hello world builder, we want the user to configure who we are saying hello to, so we
define one attribute named target for this purpose. The user should see the single text
field for this, so we choose the type accordingly. The display name and inline help are
self-explanatory. They control what the user will see when they are editing their freestyle projects to use our new builder.
The second question you should ask when you define a template is how does it
execute? (or more generally how does it map to the terms Jenkins understands?)
The answer to that question becomes the transformer. In this tutorial, our builder will
turn into a shell script that says hello (whereas your real template would probably
turns into a shell script that gets some real work done or your template can translate
into any other builders, but see the rest of the user guide for that.) So well choose
generate a shell script to execute via Groovy.
47
Template Plugin
In the text area, well fill the shell script that this build step is going to execute,
but with expressions here and there of the form ${...} (because this is a Groovy
template). ${target} refers to the actual value of the target attribute we defined
above, and ${build.fullDisplayName} is a Groovy expression to access the
getFullDisplayName() method (which returns the full name of the build) of the build
object, which refers to the current build in progress. The ${build.fullDisplayName}
needs to be quoted because this is going to look like test #1, and # gets interpreted by
shell as a comment sign unless you quote it.
Figure 8.3 captures this template configuration. When you are done, click Save to
save this template. Your template is now ready.
Figure 8.3. Configuring a hello world builder

48
Template Plugin
8.2.2. Use a template

Now that we have our first builder template, lets create a free-style project that
actually uses it. Go back to the Jenkins top page, and create a new free-style project.
Youll be taken to the configuration page. This part of Jenkins should be already
familiar to you.
When you click add build step, you should see the newly created Say Hello World
builder. You click it, and you see the say hello world builder added to your project.
And you see the target attribute you defined in the configuration page, as depicted in
Figure 8.4.
Figure 8.4. Using a hello world builder

I configured this project to say hello to Kohsuke. Click save, and schedule a new build.
In its console output, you should see something like this:
[workspace] $ /bin/sh -xe /tmp/hudson2322666548865862105.sh
+ echo Hello to Kohsuke from test #1
Hello to Kohsuke from test #1
Finished: SUCCESS
So the template is running as expected.
8.2.3. Changing the template definition

Lets change the definition of the template, and see how it affects the instances.
49
Template Plugin
Well go back to the template definition by going back to the top page, clicking the
Templates link in the left, and clicking the configuration icon on the right to the Say
Hello World template.
Instead of saying hello, now we make it say good evening.Click save to save this
new definition:
Figure 8.5. Updating hello world builder template

Now, when you update the template definition, all the use of this template
automatically reflects the change you made. So without revisiting the configuration
page of the freestyle job, lets simply schedule another build and see its console output:
[workspace] $ /bin/sh -xe /tmp/hudson2322666548865862105.sh
+ echo Good evening to Kohsuke from test #2
Good evening to Kohsuke from test #2
Finished: SUCCESS
Our change was indeed reflected.
8.3. Tutorial: job template for Jenkins plugin

In the second tutorial, we look at a more complex template that templatizes a whole
job.
To set the context for this tutorial, look at Jenkins-on-Jenkins1 (Figure 8.6), which is
the Jenkins server that the Jenkins community runs for itself. On this Jenkins, there are
a large number of jobs that build the community-maintained Jenkins plugins:
http://ci.jenkins-ci.org/
50
Template Plugin
Figure 8.6. Jenkins on Jenkins

51
Template Plugin
The actual configuration of all these jobs are almost identical. They each check out
a Git repository, run mvn -e clean install, send an e-mail at the end of the build, and
update JIRA issues thats discovered in the commit messages.
Each time we add a new plugin, we copy from one of the existing plugins, change
the name, and then call it done. But if tomorrow we want to install a new plugin (say
we start sending the results to IRC via IRC plugin) and make a mass change to all the
plugins, thats hopelessly tedious.
This is a prime use case for the template plugin. So lets turn this into a template.
8.3.1. Creating a template

First, we go to the top page, click Templates link and click New Template. Well
then create a new job template. Because this template is for building Jenkins plugin,
we call Jenkins Plugin. Screenshot in Figure 8.7:
Figure 8.7. Creating a job template

As with the previous tutorial, we just ask ourselves what does the user (plugin
developer) need to configure, and in our case, it just involves one question, which is
whether the plugin is in Git, or if its still in Subversion (aside from the name attribute,
which is there by default.)
So in the attribute, we define the scm attribute to be a choice between Git and
Subversion as showin Figure 8.7:
52
Template Plugin
Figure 8.8. "SCM" attribute in the template

Further down below, we configure the template to refer to jobs as plugins. While this
change is purely cosmetic and only affects whats shown in the HTML for humans, it
nonetheless makes it easier for users to understand, because in this context, plugin is
a well-defined technical term that has specific meaning, while job is not.
53
Template Plugin
Figure 8.9. Changing the pronoun of the template
8.3.2. Defining transformation

Unlike the previous tutorial where we defined a builder template in terms of the
transformation into a shell script that we execute, defining a transformation for a job
template is more involving.
The idea here is that we need to tell the template plugin how our model definition (that
consists of the name attribute and the scm attribute) maps to the actual job definition
that Jenkins understand (in our case thats Maven2 job type). We do this by defining a
transformation from the model into the XML persisted form of the Maven2 job type.
The template plugin uses this transformation to obtain the XML, then load it up to
Jenkins so that it understands how to run it.
So in this tutorial, we use Jelly based transformation. Jelly2 is a template language
that generates an XML. It is like a JSTL on steroid, and as long as your transformation
doesnt have a complex computation, its a reasonable choice.
The best way to define this transformation is by doing programming by example
that is, we manually configure one representative project, then obtain its XML
representation. In our case, we use the accurev plugin3 as such a representative job,
so well obtain its XML representation by simply adding config.xml to this URL at
http://ci.jenkins-ci.org/view/Plugins/job/plugins_accurev/config.xml.
Next, we take this XML and insert variables where appropriate. For example, you see
an occurrence of accurev in the git configuration, so we replace that with ${name} as
below:
<scm class="hudson.plugins.git.GitSCM">
<userRemoteConfigs>
<hudson.plugins.git.UserRemoteConfig>
...
<url>git://github.com/jenkinsci/${name}-plugin.git</url>
</hudson.plugins.git.UserRemoteConfig>
</userRemoteConfigs>
2
3
http://commons.apache.org/jelly/
http://ci.jenkins-ci.org/view/Plugins/job/plugins_accurev/
54
Template Plugin
Theres one more reference of accurev down in the root module, but this is an
inferred value (we can tell because we are never asked to enter this information in
the configuration page.) So we can simply remove the entire <rootModule> element.
Unless you know the internals of Jenkins, this is a bit of a trial-and-error. Similarly,
if you want to keep XML concise, you can remove a large number of elements from
the configuration XML and Jenkins will still happily read it and provide default values
(again, this involves a bit of trial-and-error in the general case, although there are some
rule of thumbs. for example, boolean fields are always safe, so are most string fields.)
We also need another XML from a plugin thats building in Subversion to complete
this transformation. For this, we look at the configuration of the Subversion plugin4
(which lives in the Subversion repository, somewhat unsurprisingly.) You can spot the
section that configures Subversion, so we do the same variable insertion, and the result
is as follows:
<scm class="hudson.scm.SubversionSCM">
<locations>
<hudson.scm.SubversionSCM_-ModuleLocation>
<remote>https://svn.jenkins-ci.org/trunk/hudson/plugins/${name}</remote>
</hudson.scm.SubversionSCM_-ModuleLocation>
</locations>
...
</scm>
Now, we want to switch between two fragments depending on the value of the
scm attribute. To do this, we use a tag library from Jelly that does the switch/case
equivalent, called choose/when (XSLT has the same elements that do the same thing.)
So where we had the scm tag, we add the following fragment:
<j:choose xmlns:j=jelly:core>
<j:when test="${scm=='git'}">
<configVersion>2</configVersion>
<userRemoteConfigs>
<name>origin</name>
<refspec>+refs/heads/*:refs/remotes/origin/*</refspec>
<branches>
<hudson.plugins.git.BranchSpec>
<name>master</name>
</hudson.plugins.git.BranchSpec>
</branches>
<buildChooser class="hudson.plugins.git.util.DefaultBuildChooser"/>
<gitTool>Default</gitTool>
4
http://ci.jenkins-ci.org/view/Plugins/job/plugins_subversion/config.xml
55
Template Plugin
<submoduleCfg class="list"/>
</scm>
</j:when>
<j:when test="${scm=='svn'}">
<locations>
</locations>
<workspaceUpdater class="hudson.scm.subversion.UpdateUpdater"/>
</scm>
</j:when>
</j:choose>
See Jelly tag library reference5 for more about these tags. The entire transformation
Jelly script is as follows:
<?xml version='1.0' encoding='UTF-8'?>
<maven2-moduleset>
<actions/>
<description></description>
<properties>
<hudson.plugins.disk__usage.DiskUsageProperty/>
</properties>
<j:choose xmlns:j="jelly:core">
<j:when test="${scm=='git'}">
<configVersion>2</configVersion>
<userRemoteConfigs>
<name>origin</name>
<refspec>+refs/heads/*:refs/remotes/origin/*</refspec>
<branches>
<hudson.plugins.git.BranchSpec>
<name>master</name>
</hudson.plugins.git.BranchSpec>
</branches>
<buildChooser class="hudson.plugins.git.util.DefaultBuildChooser"/>
<gitTool>Default</gitTool>
<submoduleCfg class="list"/>
</scm>
</j:when>
<j:when test="${scm=='svn'}">
5
http://commons.apache.org/jelly/tags.html
56
Template Plugin
<locations>
</locations>
<workspaceUpdater class="hudson.scm.subversion.UpdateUpdater"/>
</scm>
</j:when>
</j:choose>
<canRoam>true</canRoam>
<jdk>(Default)</jdk>
<triggers class="vector">
<hudson.triggers.SCMTrigger>
<spec>*/15 * * * *</spec>
</hudson.triggers.SCMTrigger>
</triggers>
<goals>-e clean install</goals>
<defaultGoals>package</defaultGoals>
<mavenName>maven-3.0.3</mavenName>
<mavenValidationLevel>0</mavenValidationLevel>
<aggregatorStyleBuild>true</aggregatorStyleBuild>
<reporters/>
<publishers />
<buildWrappers/>
</maven2-moduleset>
Now we save the configuration, and our job template is ready.

Go back to the top page, and click New Job. Youll see the newly created template
as one of the options:
57
Template Plugin
Figure 8.10. Creating a new plugin job

So we type in the name of the plugin that we want to build, say git, then click OK.
The configuration page of this job cannot be any simpler:
58
Template Plugin
Figure 8.11. Creating a new plugin job

The git plugin lives in the Git repository, so choose that, and save. Lets schedule a
new build, and see it build the plugin.
8.4. Concepts
A template is a reusable piece of configuration that only exposes a minimal set of
parameters to users, and is internally translated to a standard Jenkins configuration.
Thus, a template can be used to expose a simplified, abstract, restricted representation
of Jenkins job configuration to users. Changes to a template immediately apply to
everywhere the template is used.
59
Template Plugin
A template is conceptually broken down into a few pieces:
Key concepts in the template plugin
Model
A model defines a set of attributes that constitutes a template. Roughly speaking,
you can think of this as a class of an object-oriented programming language. For
example, if you are creating a template for your organizations standard process
of running a code coverage, you might create a model that has attributes like
packages to obtain coverage, tests to run.
Attribute
An attribute defines a variable, what kind of data it represents, and how it gets
presented to the users. This is somewhat akin to a field definition in a class
definition.
Instance
An instance is an use of a model. It supplies concrete values to the attributes
defined in the template. Roughly speaking, the model-to-instance relationship
in the template plugin is like the class-to-object relationship in a programming
language. You can create a lot of instances from a single template.
Transformer
A transformer is a process of taking an instance and mapping it into the
standard Jenkins configuration, so that the rest of Jenkins understands this and
can execute it. This can be logically thought of as a function.
When we say template it actually is a combination of a model and a transformer.
And each facet of these concepts are individually extensible --- for example, additional
transformers can be developed to let you express the transformation in the language of
your choice.
8.4.1. Models
Models are hierarchical and can extend other models. This can be used to create
some common usage templates, that are not designed for direct usage and will not
be instantiable by users, and create concrete templates by specializing them for a
dedicated task. When a model inherits another, it inherits all the attributes that are
defined in the base model.
For example, a common utility template can handle connection and authentication to
enterprise infrastructure, and child templates can use this basis to expose high-level
tasks, like deploying a new release.
Template hierarchy is a useful way to manage templates growing complexity and
mutualize attribute definition.
60
Template Plugin
Template can be configured as being instantiable by users, or only a way to
encapsulate some configuration to be used from other template by inheritance.
Templates have a dedicated entry in the top page, where the administrator will setup
and maintain the templates.
All templates are based on generating Jenkins configuration from a reduced set of
attributes, that the user will provide to apply the template for a dedicated job. This
major complexity reduction makes configuring new jobs very simple for new users and
reduce the risk of misconfiguration.
8.4.2. Attributes
Each attribute represents a fragment of data that constitutes a template, along with
how it gets presented in the UI to the users. For example, you might define an attribute
called "product code", which stores a string represented in the single-line text field.
Each attribute consists of the following data model:
Data model of attributes
ID
IDs uniquely identify an attribute among other attributes of the same model. ID
is used to refer to an attribute in transformers and other places, so the characters
you can use in ID are restricted.
Display Name
Display name is the human-readable name of the attribute. It is used for example
when Jenkins present the configuration page to edit an instance.
Type
The type of the attribute primarily determines the type of the data that this
attribute holds (such as string, boolean), but it also controls how the data is
represented in the UI (for example, is it a single-line text field or a multi-line text
area?) For the discussion of available attribute types, see Section 8.5, Attribute
Type Reference.
8.5. Attribute Type Reference

The template plugin ships with the following distinct attribute types. Attribute types
are also extensible, allowing additional plugins to bring in more types.
8.5.1. Text field

This attribute type holds arbitrary string value that can be edited through a single line
text field. It is the most general purpose attribute type.
61
Template Plugin
Transformers access these values as java.lang.String values.
8.5.2. Text area

This attribute type holds arbitrary string value that can be edited through a multi-line
text area. This is suitable for entering large chunk of text.
Transformers access these value as java.lang.String values.
8.5.3. Checkbox
Checkbox holds a boolean value that can be edited through an HTML checkbox.
Transformers access these values as boolean values.
8.5.4. Nested Auxiliary Models

Nested auxiliary model allows a model to compose other models. See auxiliary models
for more discussion.
It supports three different sub-modes.
Single value
The attribute will hold one and only one instance of the specific auxiliary
model. In the UI, the configuration of the nested auxiliary model is presented
as-is, inline. Lets say you created an auxiliary model that represents the access
credential to your internal package repository called PackServer Credential.
You then create Acme Corp Pack Build template that builds and deploys a
binary to this package server. This template would want to have an attribute that
holds a Credential auxiliary model as a nested value in the single mode, since
you need one and the only one credential for each job.
List of values
The attribute will hold a list of instances. All the instances must come from a
single auxiliary model, but users can add as many/few of them as they wish.
A good example of this is the JDK configurations in the system configuration
page (where JDK can be thought of as an auxiliary model, which in turns has
attributes like name, home, installer, etc.) The UI of this mode will be just like
that of the JDK configuration. A button to add/remove/reorder instances of the
auxiliary model.
List of values, including subtypes
This is similar to the list of values mode above, except that the user can choose
from all the instantiable subtypes of the specific nested model type. A good
example of this is the build step configuration in a free-style project, where you
62
Template Plugin
can add any number of build steps (which are all subtypes of the base model
called Builder.) This mode presents a drop-down menu button that allows the
user to choose the specific auxiliary model type to instantiate.
Transformers access these values as an instance (or as a java.util.List of instances)
of auxiliary models. In the pack server / credential example above, you could access it
like i.credential.username (where i is the instance of the outer model, credential
is the ID of the attribute, and username is the ID of an attribute of the Credential
auxiliary model.)
8.5.5. Select a string among many

This attribute type is like an enumeration type. The designer of a model can specify a
list of name/value pairs, and the user of the model gets to choose one of the pairs as
the value. The UI will show the name part of the pair, and the transformers will see the
value part of the pair, which mimics how the
<xml><select></xml>
tag works in HTML.
The designer of a model can choose different UI presentation for the attribute.
8.5.6. Computed Value

This is a special type of attribute, whose value is a result of evaluating a JEXL
expression, which is specified during the model definition. The value isnt editable in
the instance configuration screen. This is somewhat akin to defining a getter method
(whereas the regular attribute definitions are like defining fields); it lets you specify a
program that computes the value, typically based on the value of other attributes.
There are a number of use cases for such a property:
To simplify the transformer definition. If your transformer keeps doing a similar
manipulation of attribute values over and over again, it is often better to define
such a manipulation as a computed attribute (for example, say you define an
attribute for a subversion repository URL, and you want its last path component
accessible as a separate attribute.)
For polymorphic behavior in auxiliary models. Imagine you are defining a model
for assembling a book from its chapters, where each chapter can be either a preexisting PDF in your content repository or a docbook that needs a transformation.
You define this as a base abstract auxiliary model called Chapter and then two
concrete sub-models. Those sub-models likely define different set of parameters,
but its often convenient for them to both have the attribute of the same name (say
shellScript that evaluates to the shell script that produces PDF) that yield very
different values that are computed from other attributes.
63
Template Plugin
At runtime, the actual type of the attribute depends on the expression.
8.5.7. Model Transformer

This attribute type holds a configured instance of a model transformer. This is
primarily introduced for defining the meta-model that the template plugin internally
uses, and probably of limited use for typical models.
At the instance editing time, this attribute will be rendered as a drop-down box to
choose available transformer type, which then unfolds whatever UI specific to the
selected transformer type.
At runtime, this attribute is accessed as an instance of
com.cloudbees.hudson.plugin.modeling.transformer.ModelTransformer
Java
type.
8.5.8. Heterogeneous components from descriptors

This advanced attribute type allows a model to hold a collection of arbitrary
6
Describable instances. The discussion of the Describable class and its role in
Jenkins goes beyond the scope of this document, but this allows models to reuse
plethora of information fragments defined in plugins large and small (such as
Subversion checkout location, builders, ...)
Of various attribute types that deal with Descrbables, this attribute type holds a list of
them, and it allows all the subtype Describables for the specified base type. A good
example of this is the build step configuration in a freestyle project, where users can
insert any build steps of various types, so long as they extend the base "build step"
type.
8.5.9. Heterogeneous components from descriptors (one instance per

descriptor)
This attribute type is a flavor of Section 8.5.8, Heterogeneous components from
descriptors. This version alsoholds a list of Describables, but it only allows upto one
instance from one type. A good example of this is the post-build action configuration
in a freestyle project, where users can activate arbitrary number of publisers of various
types, but only up to one per type.
8.5.10. Select another model

This attribute type holds a reference to a model. This is primarily defined for the metamodel that the template plugin internally uses, and probably of limited use for typical
models.
6
http://javadoc.jenkins-ci.org/hudson/model/Describable.html
64
Template Plugin
At the instance editing time, this attribute will ask the user to choose a model out of all
the models defined in Jenkins.
At runtime, this attribute is accessed as an instance of
com.cloudbees.hudson.plugin.modeling.Model Java type.
8.5.11. Select item

This attribute type holds a reference to an item in the Jenkins. Item is the
generalization of the top level elements of Jenkins, like maven and freestyle jobs,
matrix jobs, folder, etc.
This attribute type can be further constrained by the kind of item it can refer to. This
can be done in terms of the job type in Jenkins, or the template it is created from. For
example, if you are modeling a test job to be run after a build job, your test job model
would need to refer not just random item in Jenkins, but items thats created from the
build job type.
At runtime, this attribute is accessed as an instance of hudson.model.Item.
8.6. Builder Template

Often, developers create build steps as shell scripts to address enterprise requirements,
for e.g: custom deployments, packaging, notification, QA integration, etc. The same
script is used across a large set of jobs and only differ by few attributes. Maintaining
such scripts and avoiding copy/paste mistakes can be a nightmare on large Jenkins
installations. The builder template creates a new type of builder, thereby eliminating
the need of copying a script, and highlighting the things that need to be filled in by
users.
A similar goal can be achieved by a custom plugin development. A builder template,
compared to a custom plugin, has the following trade-offs:
Writing a plugin requires a significant one-time learning cost, compared to
writing a template, whereas a simple template can be developed rapidly. So for
simple things, templates tend to get the job done more quickly.
A template can be created, modified, removed without restarting Jenkins
You get a lot more tool assistance for a plugin development, thanks to the great
IDEs available for Java. So for complex things, plugins tend to get the job done
more quickly and elegantly.
Compared to job templates, builder templates tend to be more flexible, as the person
configuring jobs still have substantial freedom to control how it works. Builder
65
Template Plugin
template is also the easiest kind of templates to create, especially in combination
with the specialized transformers that generate shell scripts. This makes the builder
templates the best entry point to the template plugin.
8.6.1. Creating a new Builder Template

The new template wizard offer few options, including that of creating a new Builder
Template as shown in Figure 8.12. The template configuration allows administrator to
define the execution details of any custom tool, that will be exposed to users as a new
build step.
Figure 8.12. Creating a new builder template
8.6.2. Defining Transformer

The transformer controls how your build template maps to the actual builder that
carries out the build.
One way to define a transformer is to use one of the standard transformers that takes an
instance and produces an XML (in this case, the XML should match the XML created
from one of the build step.) As we discussed in the tutorial, a good way to do this is
programming by example, where you manually create a freestyle project and configure
it, then observe what XML it is producing.
The other way to do this, which is often preferrable, is to use one of the specialized
transformers that only work with builder templates, which we'll discuss below.
66
Template Plugin
8.6.2.1. Generate shell script via Jelly/Groovy
For shell scripts, a simpler way to define a builder template is to generate the script
using Jelly or Groovy instrumentation to process the attributes and generate the
adequate script. These specialized transformers eliminate the need of programming by
example by focusing on the shell scripts.
See the transformer reference section for more details about the general syntax of Jelly/
Groovy template, as well as available variable bindings.
The following screenshot demonstrates a groovy generated shell script to run the
du command on an arbitrary user home directory. The ${...} in the text should
not be confused with the shell variable reference. These are expanded during the
transformation before it gets passed to shell.
Such templates are easy to create for Unix administrator to automate maintenance
processes, and can be use to give users the ability to run them without the risk to allow
arbitrary command to be executed.
Figure 8.13. Generate Shell Script via Jelly/Groovy

8.6.2.2. Template evaluation timing
Another key difference of these specialized transformers is the difference in the timing
of the template evaluation. The general purpose transformers perform transformation
asynchronously from the execution of builds (roughly speaking, think of it as
transforming right after the job is configured), whereas these shell script transformers
run during the build.
67
Template Plugin
This allows you to perform contextual transformations that depend on the parameters
and conditions of the in-progress build (such as the changes in the source code, what
started it, etc.)
To do so, use the build variable from within your template to access the
7
AbstractBuild object that represents the current build in progress.
8.7. Job Template

Usually, in many enterprise contexts, you end up with multiple jobs that differ just
by few things; such as where the code is checked out from, or the QA servers that are
used. Job templates can be used to represent this model in enterprise development by
letting projects only define the minimal variable configuration to apply to the model.
Thus, job template offers a higher level of abstraction, as it templates the definition of
a whole job.
One typical use case of this is that you have lots of components that are written and
built the same way. The OSS Jenkins project, for example, has a large number of
plugins that are built precisely in the same way. It makes sense to define a template
for this, as we did in the tutorial, to centralize the configuration and make it easier to
create a new job for a new plugin.
Another typical use case of this is that you have multiple branches of the same project,
actively developed simultaneously. Such jobs tend to be only different in where they
check out the code, and making a template out of it allows you to rapidly set up CI for
new branches.
Another use case of the job template is where there is a gap in the Jenkins expertise
between the Jenkins experts in your organization and the developers at large. Template
can be useful to dumb down the user interface and steer them toward the set of
boundaries the experts set, thus gaining overall productivity for them.
A custom job type can be also developed as a plugin, but this is one of the most
complex extension points in Jenkins. For this reason, we recommend you first start
with the job template, and only after you start feeling the constraints of the template
plugin you consider re-writing it as a custom plugin.
8.7.1. Configuration
Job templates need to produce a full job XML definition as a result of the
transformation. As discussed in the tutorial, often the simplest way to get this done
is programming by example. You manually create a project (or a few), configure it
with all the desired options, and then get the config.xml file by adding config.xml
to the URL, then insert expressions and statements where you need to reflect actual
values from instances.
7
http://javadoc.jenkins-ci.org/index.html?hudson/model/AbstractBuild.html
68
Template Plugin
Figure 8.14. Job Templates

A job template will also maintain a list of projects that are using the template, so that
an administrator can quickly check the project that follows the success of project
structure standardization.
8.8. Folders Template

Folders are another Jenkins Enterprise feature, described in another document. It
allows you to group related jobs and organize them in a hierarchical way, as youd do
with files and directories on a file system.
As a container of jobs, a folder template is an useful way to define a set of jobs that
follow enterprise rules and best practices. For example, a single folder template could
instantly provision a set of jobs that implement your organizations best practice, for
example (1) a CI job that builds the tip of the repository every time a commit is made,
(2) a continuous inspection nightly job to populate a sonar server with code quality
metrics, and (3) a continuous deployment job to push successful builds to a demo
server for dogfood eating.
A folder template can be also useful to clarify the flavor of a folder and how its
supposed to be used. For example, you might have a template for a product, and
which contains branch folders that are templates themselves (say because you need
multiple jobs for one branch.) Such modeling enables you to now capture relationship
between your products as model attributes, which can then translate into lower level
configuration, such as trigger relationship.
69
Template Plugin
8.8.1. What a folder template controls and what it doesnt

Folder template controls the configuration of a folder itself (that is, everything that
appears in the configuration page of the folder), such as the name, the icon, views, and
access control matrix.
A folder template also allows you to specify a set of activities that are to be performed
when a new instance of the template is created, such as creating jobs inside the new
folder, as can be seen in the screenshot below:
Figure 8.15. Folder Templates

But beyond the initial creation, jobs inside a folder arent controlled by templates.
So with sufficient permissions, users can add/remove jobs and the template change
will not void those changes. If this is undesirable and you prefer to lock things
down further, you can use job templates for jobs in a folder template (to restrict the
configuration freedom) and use access control to prevent creation/deletion (see RBAC
documentation for more details.)
8.8.2. Folder features that work well with templates

There are several features in the folder plugin that works really nicely when combined
with a folder template.
8.8.2.1. Restrict child type in a folder
A folder can be configured to restrict the kind of items that it can contain. When you
define a folder template, this is useful way of strengthening the flavor of a folder.
70
Template Plugin
For example, you can say a product folder template can only contains branch folder
templates.
8.8.2.2. Environment variables
A folder can be configured to define a set of environment variables that are
automatically made visible to all the builds inside the folder. This is one of the primary
ways to use the template attributes and have them affect what goes on inside a folder.
In the earlier example of a folder template that represents a branch, you can define
the environment variable called BRANCH, and all your jobs can refer to this variable to
choose where to check out the code from.
8.8.2.3. Model attribute list view column
The template plugin adds a new list view column extension, which lets you display
values of the specified attribute from items in the container.
This list view column is useful when you have a folder (or a view) that contains
items created from job templates / folder templates. For example, if you have a
folder template that represents a product, which in turn contains folder templates that
represent branches, you can show the name of the branches in a list view inside the
product.
This can be further combined with the computed value attribute type to further
control what to display.
8.9. Auxiliary Template

Auxiliary templates are second-class citizens that are used to create inner structures
in other models. As such, they do not get transformed to any Jenkins concepts by
themselves.
It is easier to understand an auxiliary template if you think about how youd model
a music CD. A music CD model might have properties like title and the year of
publication, but it also has a list of tracks, where a track by itself is a model that has
several attributes, such as the title, the duration, and the composer. In this example, a
track is an auxiliary model.
Auxiliary model is also useful for a set of information appear repeatedly across
different models. For example, your software development might involve accessing
database, which requires several attributes to model (say host, schema, user name, and
password.) So as you define various templates that use database, it is convenient to
define the database access as an auxiliary model and refer to it from other templates.
(The other way to do this of course is via inheritance, where you define this set
of attributes in the base template and derive from it elsewhere. See the extensive
discussion between inheritance vs composition in object oriented programming
languages for more analogy and trade-offs.)
71
Template Plugin
8.9.1. Accessing attributes of auxiliary instances

When you define a model that contains instances of auxiliary models, your
transformation will want to access these attributes. See Section 8.5.4, Nested
Auxiliary Models for more details.
8.10. Transformer Reference

The template plugin comes with a number of built-in transformer implementations. As
discussed in the Concepts section, logically speaking a transformer is a function that
takes an instance and generates the standard Jenkins configuration of something (be
it a builder, a job, ), thereby describing the model in terms that the rest of Jenkins
understands.
This chapter walks through all the available transformer implementations.
8.10.1. Jelly-based transformation

Jelly8 is an XML-based template engine. Firstly, it allows you to insert arbitrary Javalike expressions in the ${...} syntax (see JEXL9 for the reference of this syntax),
and secondly, it allows you to use tags to do basic control-flow operations, such as
conditional block, for-loop, switch/case, etc. See Jelly core tag library reference10 for
more details.
Another benefit of Jelly is that it is guaranteed to produce a well-formed XML, and
anything short of that is detected while you are defining a transformer. This reduces
the chance of invalid transformer configuration.
Through these tags, Jelly can be abused as a programming language, but that is
not really what Jelly is designed for (although at times this is handy.) If you start
finding yourself using more Jelly tags than literal XML elements, consider using other
transformers, such as Groovy template transformation, which offers more concise
syntax.
8.10.1.1. Variable Bindings
During the transformation, all the attributes of the instance are available by their IDs.
In addition, the following special variables are available:
instance
this variable refers to the instance object being transformed. This is of type
com.cloudbees.hudson.plugins.modeling.Instance.
8
http://commons.apache.org/jelly/
http://commons.apache.org/jexl/reference/syntax.html
10
http://commons.apache.org/jelly/tags.html
9
72
Template Plugin
model
this variable refers to the model that the instance belongs to. This is of type
com.cloudbees.hudson.plugins.modeling.Model.
These variables and their methods/properties can be accessed to perform intelligent
transformation.
8.10.2. Groovy template transformation

This transformer is based on Groovy template11, which is essentially a JSP in Groovy
syntax + ${...} style expression, such as the following:
<foo>
<%
for (int i=0; i<100; i++) {
if ((i%2)==0) {
%>
<data>${i}</data>
<%
}
}
%>
</foo>
The benefit of this transformation is that the Groovy syntax, with its close alignment
with the Java syntax, makes it easier for Java programmers to perform complex
transformation.
8.10.2.1. Variable Bindings
This transformer exposes the exact same set of variables as the Jelly transformer.
8.11. Advanced Template Techniques

In this section, we discuss various techniques to create and maintain sophisticated
templates.
8.11.1. Navigating around objects in context

Sophisticated templates require accessing information available in the rest of the
Jenkins object model. For example, lets say your test job template has an attribute
that refers to the corresponding build job, and youd want the test job to change its
behaviours based on the configuration of the build job.
This kind of template can be best written as Groovy-based transformer, since it
provides concise syntax to navigate around the object model and access information.
11
http://groovy.codehaus.org/Groovy+Templates
73
Template Plugin
8.11.1.1. Instance to Item, Item to Instance
The Instance type refers to a Map-like object that retains the values of attributes for a
model, and during the transformation, the current instance is always accessible as the
instance variable.
When those instances are from templates that map to jobs in Jenkins
(such as job template and folder template), these instances are of the
com.cloudbees.hudson.plugins.modeling.impl.entity.EntityInstance
class, which defines the item property that lets you access the corresponding
hudson.model.Item instance (such as FreeStyleProject object and a Folder object.)
So for example, instance.item.isDisabled() would check if the job is disabled or
not.
Conversely, those items that are created from their templates have the instance
property that allows you to navigate back to the instance. In other words,
instance.item.instance==instance. For items that are not created from any
templates, this property returns null. Also note that this property is defined in Groovy,
and not in Java, and therefore it is only accessible when using Groovy transformers.
74
Chapter 9. VMware Pool Auto-Scaling

Plugin
9.1. Introduction
The VMware plugin connects to one or more VMware vSphere installations and uses
virtual machines on those installations for better resource utilization when building
jobs. Virtual machines on a vSphere installation are grouped into named pools. A
virtual machine may be acquired from a pool when a job needs to be built on that
machine, or when that machine is assigned to a build of a job for additional build
resources. When such a build has completed, the acquired machine(s) are released back
to the pool for use by the same or other jobs. When a machine is acquired it may be
powered on, and when a machine is released it may be powered off.
This plugin has been tested on VMware vSphere 4.1 and is compatible with version 4.0
and greater. This plugin version is backwards compatible with previous 1.x versions.
The plugin was introduced in Nectar 10.10 and updated significantly in Nectar 11.10
9.2. Configuration
Before jobs can utilize virtual machines it is necessary to configure one or more
machine centers, that connect to vSphere installations, and one or more machine pools
from within those machine centers, from which builds may acquire machines.
From the main page click on "Pooled Virtual Machines", then click on "Configure" to
goto the plugin configuration page.
After configuration the "Pooled Virtual Machines" page will display the current list
of configured machine centers. From this page the click on a machine center to see
the list of machine pools, and from that page click on a machine pool to see the list of
machines.
9.2.1. Machine Centers

To configure a machine center enter a name for the center, which will be referred to
later when configuring clouds or jobs, the host name where the vCenter service is
located that manages the vSphere installation, and the user name/password of the user
to authenticate to the vCenter and who is authorized to perform appropriate actions on
machines in pools.
One or more machine centers may be configured to the same or different vCenter. For
example, different pools may require different users that have authorized capabilities
to the same vCenter, or there may be multiple vCenters that can be used. Details can be
verified by clicking on the "Test Connection" button.
75
VMware Pool Auto-Scaling Plugin
9.2.2. Machine Pools

One or more machine pools may be added to a machine center. There are currently two
types of machines pool that can be added. A static pool and a folder pool. In either case
power-cycling and power-on wait conditions may be configured for all machines in
such pools.
It is guaranteed that a virtual machine will be acquired at most once, even if that
machine is a member of two or more pools of two or more centers.
9.2.2.1. Static Pools
To configure a static machine pool enter a name for the pool, which will be referred
to later when configuring clouds or jobs. Then, add one or more static machines to the
pool. The name of the static machine is the name of the virtual machine as presented in
the vCenter.
Note that there can be two or more virtual machines present in the vCenter with the
same name, for example if those machines are located in separate folders or vApps. In
such cases it is undetermined which machine will be associated with the configuration.
If the machine is assigned to a build then a set of optional properties, "Injected Env
Vars", can be declared that will be injected into the build as environment variables.
9.2.2.2. Folder Pools
To configure a folder machine pool enter a name for the pool, which will be referred
to later when configuring clouds or jobs. Then, declare the path to a folder or vApp
where the machines contained in that folder or vApp comprise of the pool of machines.
If the "recurse" option is selected then machines in sub-folders or sub-vApps will also
be included in the pool.
If the machine is assigned to a build then IP address of the virtual machine will be
declared in environment variable "VMIP" that is injected into the build.
Virtual machines may be added and removed from the folder or vApp without
requiring changes to the configuration. Such pools are more dynamic than static pools.
9.2.2.3. Power Cycling
Power-on actions can be specified after a machine has been acquired from a pool, but
before the machine has been assigned to a build. Power-off actions can be specified
after a build has finished with the machine, but before that machine has been released
back to the pool.
The set of power-on actions are as follows:
Power up
Powers up the machine. If the machine is already powered up this action does
nothing.
76

Revert to last snapshot and power up
Revert the machine to the last known snapshot, and then power up. This can be
useful to power up the machine in a known state.
Do nothing
No actions are performed on the machine and it is assumed the machine is
already powered on.
The set of power-off actions are as follows:
Power off
Powers off the machine. This can be useful to save resources. Note that it can
take some time for a machine to be powered on and fully booted, hence builds
may take longer if the power-cycling represents a significant portion of the
overall build time.
Suspend
Suspend the machine. This can be useful to save resources while being able to
power on the machine more quickly.
Take snapshot after power off
Power off the machine, and then take a snapshot.
Take snapshot after suspend
Suspend the machine, and then take a snapshot.
Do nothing
No actions are performed on the machine, and it will be left powered-on.
9.2.2.4. Power-on Wait Conditions
After a machine is powered on, if power-on actions are configured, and before the
machine is assigned to a build, certain wait conditions may be configured that ensure
the machine is in an appropriate state.
The set of power-on wait conditions are:
Wait for a TCP port to start listening
A timeout, default of 5 minutes, can be specified. If waiting for the TCP port to
become active takes longer that the timeout, then the machine will be released
back to the pool and an error will result.
Wait for VMware Tools to come up
Optionally, also wait for the machine to obtain an IP address. A timeout, default
of 5 minutes, can be specified. If waiting for VMware Tools takes longer that
the timeout, then the machine will be released back to the pool and an error will
result.
77
9.3. Building Jobs on Virtual Machines

To declare a machine pool as a slave pool, where machines in the pool are slaves used
to build jobs, it is necessary to configure a VMware cloud. From the main page of
Jenkins click on "Manage Jenkins", click on "Configure", goto the "Cloud" section,
click on the "Add a new cloud", and select "Pooled VMware Virtual Machines". Select
the machine center and a pool from that machine center that shall be used as the pool
of slaves. Then, configure the other parameters as appropriate. For example, if all
machines are Unix machines configured with SSH with the same SSH credentials then
select the "Launch slave agents on Unix via SSH".
When a build is placed on the build queue, whose label matches the configured
VMware cloud, then, a machine will be acquired from the pool, powered-on (if
configured), and added as node that is assigned to build the job after the power-on wait
conditions have been met. After the build completes the machine will be powered-off
(if configured) and released back to the pool.
Note that if there are no machines free in the machine pool then the build will wait in
the queue until a machine becomes available.
9.4. Assigning a Virtual Machine to a build

To assign a machine to a build goto the configuration page of an appropriate job, goto
the "Build Environment" section, select the "Assign a VMWare Virtual Machine to
this build", and select the machine center and a pool from that machine center that
shall be used as the pool of assignable machines.
When a build of such a configured job is placed on the build queue then, the build
will start, a machine will be acquired from the pool, powered-on (if configured), and
the build will wait until the power-on wait conditions have been met. After the build
completes the machine will be powered-off (if configured) and released back to the
pool.
Note that if there are no machines free in the machine pool then the build will wait
until a machine becomes available.
78
Chapter 10. Wikitext Plugin

10.1. Introduction
The WikiText plugin addresses security concerns that emanate from using raw HTML
in description fields in Jenkins. The plugin allows you to enter descriptions in one of
multiple wiki markup languages.
The WikiText plugin was introduced in Nectar 11.04.
10.2. Overview
Jenkins lets users enter description fields in HTML as shown in Figure 10.1. For some
teams that are concerned about XSS attacks via the description fields, or have policy
preferences towards writing wiki over HTML, this Jenkins Enterprise plugin allows
you to use one of several well known wiki markup formats in place of HTML.
Figure 10.1. Setting up project specific descriptions
10.2.1. Supported Wiki Markup Languages

The WikiText plugin supports the following wiki markup languages today:
Confluence. Click here1 for help on Confluence syntax.
MediaWiki. Click here2 for help on MediaWiki syntax.
Twiki. Click here3 for help on Twiki syntax.
Textile. Click here4 for help on Textile syntax.
TracWiki. Click here5 for help on TracWiki syntax.
1
http://confluence.atlassian.com/renderer/notationhelp.action?section=all
http://www.mediawiki.org/wiki/Help:Formatting
3
http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
4
http://en.wikipedia.org/wiki/Textile_(markup_language)
5
http://trac.edgewall.org/wiki/WikiFormatting
2
79
Wikitext Plugin
10.3. Setting up the Wikitext plugin

Enable the CloudBees Wikitext plugin in the plugin manager as shown in Figure 10.2.
Restart Jenkins Enterprise to enable the plugin.
Enable security by going to "Configure" and then "Manage Jenkins". The plugin will
be enabled.
Figure 10.2. Installing Wikitext plugin
10.4. Using the Wikitext plugin

Once the plugin is installed, click the add description link on a particular project
and enter the description in the preferred wiki markup language. In Figure 10.3, we
have used the wiki markup to render the description in bold. Figure 10.4 shows the
corresponding output.
Figure 10.3. Wikitext Usage
Figure 10.4. Wikitext Output
80
Index
P
permission, 44
Plugins
Backup, 3-4
Introduced in, 3
Restore, 4
Using, 3
Even Scheduler, 5-7
Enable, 6
Introduced in, 6
Folders, 8, 16
Enable, 8
Introduced in, 8
Using, 9
Using with RBAC, 11
Label Throttle, 12-15
Enable, 12
Introduced in, 12
RBAC, 16-41, 16
Authorization Strategy, 17, 21, 21
Concepts, Definitions, 16
Configuration, Reset, 39
Enable, 19, 19
Enable, Jenkins Changes, 19
Group, External, 17
Group, Local, 17
Groups, Configure, 24
Installation Checklist, 17
Introduced in, 16
Lockout, Recover, 37
Permission, 16
Role, 17
Role, Filter, 17
Sample, 33
Security Realm, 16
Skip Next Build, 42-44
Introduced in, 42
Using, 42
Using, Advanced, 44
Template, 45-74
Concepts, 59
Introduced in, 45
Templates
Auxiliary, 71
Builder, 65
Folders, 69
Job, 68
VMWare Auto-scaling, 75-78
VMWare Pool Auto-scaling
Build, Assign VMs, 78
Configuration, 75
Folder Pools, 76
Introduced in, 75
Jobs, Build on VMs, 78
Machine Centers, 75
Machine Pools, 76
Power Cycling, 76
Power-on Wait, 77
Static Pools, 76
Wikitext, 79-80
Enable, 80
Introduced in, 79
Using, 80
Wiki Markups Supported, 79
81

JenkinsEnterprise UserGuide 1.0 PDF

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

JenkinsEnterprise UserGuide 1.0 PDF

Caricato da

Copyright:

Formati disponibili

Jenkins Enterprise

Jenkins Enterprise by CloudBees User Guide

Jenkins Enterprise by CloudBees User Guide

Chapter 1. Introducing Jenkins Enterprise

1.1.1. Large Install Plugins

1.1.2. Optimized Utilization Plugins

Introducing Jenkins Enterprise by CloudBees

1.1.3. Security Plugins

Chapter 2. Backup Plugin

2.2. Taking Backup

2.3. Configuring Backup

2.4. Restoring From Backup

Chapter 3. Even Scheduler Plugin

3.1.1. Default Jenkins Behavior

Even Scheduler Plugin

3.1.2. Even Loading Strategy

3.2. Using Even Scheduler Plugin

3.2.1. Selecting Global Preference

Even Scheduler Plugin

3.2.2. Selecting Per-Job Preference

Chapter 4. Folders Plugin

4.3. Setting up the Folder plugin

Figure 4.1. Installing the Folders plugin

4.4. Using the Folders plugin

Figure 4.2. Creating a new Folder

Figure 4.3. Specifying parameter types for Folders

4.4.1. A sample taxonomy with the Folders plugin

Figure 4.4. Sample Taxonomy with Folders plugin

4.4.2. Using folders with other Jenkins Enterprise plugins

Chapter 5. Label Throttle Build Plugin

5.3. Setting up the Label Throttle Build plugin

This number is dependent on user specific configurations.

Label Throttle Build Plugin

Figure 5.1. Install from the plugin manager

Figure 5.2. Setup appropriate label on the slave configuration page

Label Throttle Build Plugin

Figure 5.3. Go to the labels page

Label Throttle Build Plugin

Figure 5.4. Set limit on the hypervisor

Figure 5.5. Label throttle build plugin in action

Chapter 6. Role Based Access Control

6.2. Concepts and Definitions

Role Based Access Control Plugin

6.3. Setting up the Role Based Access Control plugin

Role Based Access Control Plugin

Have you got a list of roles do you want to define?

If the security realm does not provide details of external groups

The Role Based Access Control plugin remembers its configuration

If most of your jobs will have a permissive set of permissions, but

Role Based Access Control Plugin

6.3.1. Enabling the authorization strategy

Role Based Access Control Plugin

Role Based Access Control Plugin

6.3.2. Configuring and managing roles

user defined role.

System roles cannot be removed. There are two system roles:

Role Based Access Control Plugin

Figure 6.5. Adding a role called Administrator

Figure 6.6. After clicking the Add button in Figure 6.5

Role Based Access Control Plugin

Figure 6.8. After clicking on the Check

icon for the Administrator role from