Puppet module for Jenkins
Ruby Puppet Groovy Shell HTML
Latest commit 550441e Oct 21, 2016 @rtyler rtyler committed on GitHub Merge pull request #650 from mterzo/disable_client_id
Disable swarm unique id on slave
Failed to load latest commit information.
contrib/examples Allow build jobs to be configured and managed by puppet. Includes #163 Sep 25, 2014
examples Adds Examples for various platforms for Jenkins Oct 10, 2015
files Merge pull request #636 from thomsonreuters/master Sep 21, 2016
lib retry CLI command when failure appears "network" related Jul 11, 2016
manifests Merge pull request #650 from mterzo/disable_client_id Oct 21, 2016
spec Merge pull request #650 from mterzo/disable_client_id Oct 21, 2016
templates Allow disabling clients unique ID. Oct 12, 2016
.fixtures.yml remove dependency on staging module Mar 3, 2016
.gitignore Merge pull request #275 from jhoblitt/maint/add-.bundle-to-.gitignore May 2, 2015
.rspec Work in progress, haven't figured out how to get the jenkins module s… Sep 22, 2014
.rspec_parallel Adds parallel_tests rake task Mar 17, 2016
.rubocop.yml disable Style/SpaceInsidePercentLiteralDelimiters cop Jul 7, 2016
.travis.yml bump travis puppet version matrix to 4.6/4.7 Sep 29, 2016
Blimpfile Add support for testing on RHEL 6.4 in EC2 Feb 28, 2014
CHANGELOG.md Update changelog for release Oct 14, 2015
Gemfile net-http-persisent latest version requires newer ruby Oct 12, 2016
HACKING.md fix trailing whitespace May 3, 2015
LICENSE Upgrade the copyright year to 2014 Feb 25, 2014
NATIVE_TYPES_AND_PROVIDERS.md cleanup of jenkins_job show_diff + puppet_helper optimization Apr 2, 2016
README.md Remove scary warning about Jenkins 2, which we support with 1.7.0 Aug 18, 2016
Rakefile remove travis lint from default rake target Jul 11, 2016
Vagrantfile use single quotes for ruby string literals Apr 6, 2016
bootstrap.sh fix trailing whitespace May 3, 2015
metadata.json Update metadata.json for the 1.7.0 release Aug 18, 2016



Build Status

This is intended to be a re-usable Puppet module that you can include in your own tree.

Experimental Types and Providers

The experimental types/providers are not for the faint of heart. If you are starting out with this module you probably want to skip directly to Getting Started.

A family of experimental native types and providers has been added to this module, in parallel to the existing classes and defined types, with the goal of soliciting feedback. One of the primary benefits of these new types is not requiring manifest changes to manage jenkins with or without "security" enabled. The goal is to eventually replace the functionality of the existing classes/defines with the new types. Usage feedback (positive and negative), bug reports and/or PRs would be greatly welcomed.

The semantics and API of these types should be considered unstable and almost certainly will change based on feedback. It is currently unclear if these types will be considered part of the public API or treated as private to the module.


Using puppet-jenkins

Getting Started

puppet module install rtyler/jenkins
    node 'hostname.example.com' {
        include jenkins

Then the service should be running at http://hostname.example.com:8080/.

Jenkins' options

Master Executor Threads

class { 'jenkins':
  executors => 0,

Managing Jenkins jobs

Build jobs can be managed using the jenkins::job define

Creating or updating a build job

  jenkins::job { 'test-build-job':
    config => template("${templates}/test-build-job.xml.erb"),

Disabling a build job

  jenkins::job { 'test-build-job':
    enabled => 0,
    config  => template("${templates}/test-build-job.xml.erb"),

Removing an existing build job

  jenkins::job { 'test-build-job':
    ensure => 'absent',

Installing Jenkins plugins

The Jenkins puppet module defines the jenkins::plugin resource which will download and install the plugin "by hand"

The names of the plugins can be found on the update site


By default, the resource will install the latest plugin, i.e.:

  jenkins::plugin { 'git': }

If you specify version => 'latest' in current releases of the module, the plugin will be downloaded and installed with every run of Puppet. This is a known issue and will be addressed in future releases. For now it is recommended that you pin plugin versions when using the jenkins::plugin type.

By version

If you need to peg a specific version, simply specify that as a string, i.e.:

  jenkins::plugin { 'git':
    version => '1.1.11',

Note that plugin will timeout if it takes longer than 120 seconds to download. You can increase this by specifying a timeout value, i.e: timeout => 240.


This module will download the jenkins modules over HTTP, without SSL. In order to add some verification regarding the downloaded file, you can specify a checksum. You can also define a checksum type with 'digest_type' (default to sha1 if unspecified) ie.:

  jenkins::plugin { 'git':
    version       => '2.2.12',
    digest_string => '48141822e0eea1faa1a1a99b35372494e7352c2746ca3aa3a19a07f34b021848d2cd0bffc8959c1b809c5be231c1b49e9ffec0430dd68938197ac0f34588ee25',
    digest_type   => 'sha512',

Direct URL

Direct URL from which to download plugin without modification. This is particularly useful for development and testing of plugins which may not be hosted in the typical Jenkins' plugin directory structure.

  jenkins::plugin { 'myplugin':
    source => 'https://example.org/myplugin.hpi',

Note that that when source is specified, the version and plugin_url parameters will have no effect on the plugin retrieval URL.

Plugin dependencies

Dependencies are not automatically installed. You need to manually determine the plugin dependencies and include those as well. The Jenkins wiki is a good place to do this. For example: The Git plugin page is at https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin.


You can automatically add slaves to jenkins, and have them auto register themselves. Most options are actually optional, as nodes will auto-discover the master, and connect.

Full documentation for the slave code is in jenkins::slave.

It requires the swarm plugin on the master & the class jenkins::slave on the slaves, as below:

    node /jenkins-slave.*/ {
      class { 'jenkins::slave':
        masterurl => 'http://jenkins-master1.domain.com:8080',
        ui_user => 'adminuser',
        ui_pass => 'adminpass',

    node /jenkins-master.*/ {
        include jenkins
        include jenkins::master


The dependencies for this module currently are:

Depending on Jenkins

If you have any resource in Puppet that depends on Jenkins being present, add the following require statement:

  exec { 'some-exec':
    require => Class['jenkins::package'],
    # ... etc

Advanced features

  1. Plugin Hash - jenkins::plugins
  2. Config Hash - jennkins::config
  3. Configure Firewall - jenkins (init.pp)
  4. Outbound Jenkins Proxy Config - jenkins (init.pp)
  5. CLI Helper
  6. Jenkins Users
  7. Credentials
  8. Simple security model configuration

API-based Resources and Settings (Users, Credentials, security)

This module includes a groovy-based helper script that uses the Jenkins CLI to interact with the Jenkins API. Users, Credentials, and security model configuration are all driven through this script.

When an API-based resource is defined, the Jenkins' CLI is installed and run against the local system ( Jenkins is assumed to be listening on port 8080, but the module is smart enough to notice if you've configured an alternate port using jenkins::config_hash['HTTP_PORT'].

Users and credentials are Puppet-managed, meaning that changes made to them from outside Puppet will be reset at the next puppet run. In this way, you can ensure that certain accounts are present and have the appropriate login credentials.

CLI Helper

The CLI helper assumes unauthenticated access unless configured otherwise. You can configure jenkins::cli_helper to use an SSH key on the managed system by passing the keyfile path as a class parameter:

  class {'jenkins':
    cli_ssh_keyfile => '/path/to/id_rsa',

... or via hiera:

jenkins::cli_ssh_keyfile: "/path/to/id_rsa"

Direct including of the jenkins::cli_helper class into the manifest is deprecated.

There's an open bug in Jenkins (JENKINS-22346) that causes authentication to fail when a key is used but authentication is disabled. Until the bug is fixed, you may need to bootstrap jenkins out-of-band to ensure that resources and security policy are configured in the correct order. For example:

# In puppet:
  anchor {'jenkins-bootstrap-start': } ->
    Class['jenkins::cli_helper'] ->
      Exec[$bootstrap_script] ->
        anchor {'jenkins-bootstrap-complete': }

# Code for $bootstrap_script
#!/bin/bash -e
# Generate an SSH key for the admin user
ADMIN_USER='<%= admin_user_name %>'
ADMIN_EMAIL='<%= admin_user_email %>'
ADMIN_PASSWORD='<%= admin_user_password %>'
ADMIN_FULLNAME='<%= admin_user_full_name %>'
ADMIN_SSH_KEY='<%= admin_ssh_keyfile %>'
JENKINS_CLI='<%= jenkins_libdir %>/jenkins-cli.jar'
PUPPET_HELPER='<%= jenkins_libdir %>/puppet_helper.groovy'
HELPER="java -jar $JENKINS_CLI -s groovy $PUPPET_HELPER"
DONEFILE='<%= jenkins_libdir %>/jenkins-bootstrap.done'


# Create the admin user, passing no credentials
# Enable security. After this, credentials will be required.
$HELPER set_security full_control



The defined type jenkins::cli::exec may be used to execute arbitrary CLI helper commands.

Arguments to the CLI helper script may be specified as the resource's title.

  jenkins::cli::exec { 'set_num_executors 0': }

Or passed as an array to the command parameter. This example is semantically equivalent to the first.

  jenkins::cli::exec { 'set_num_executors 0':
    command => ['set_num_executors', '0'],

which is also equivalent to:

  jenkins::cli::exec { 'set_num_executors 0':
    command => 'set_num_executors 0',

If the unless parameter is specified, an environment variable named $HELPER_CMD is declared which contains the complete string needed to execute the CLI helper script (minus arguments). This may be useful in constructing idempotent exec statements.

  $num_executors = 0
  jenkins::cli::exec { "set_num_executors ${num_executors}":
    unless => "[ \$(\$HELPER_CMD get_num_executors) -eq ${num_executors} ]"


Email and password are required.

Create a johndoe user account whose full name is "Managed by Puppet":

  jenkins::user { 'johndoe':
    email    => 'jdoe@example.com',
    password => 'changeme',


Password is required. For ssh credentials, password is the key passphrase (or '' if there is none). private_key_or_path is the text of key itself or an absolute path to a key file on the managed system.

Create ssh credentials named 'github-deploy-key', providing an unencrypted private key:

    jenkins::credentials { 'github-deploy-key':
      password            => '',
      private_key_or_path => hiera('::github_deploy_key'),

Setting a UUID:

You can also specify a UUID to use with the credentials, which will be used to identify the credentials from within the job config. This is necessary when setting credentials for use with the git plugin, for example.

You can either manually generate a UUID from a site like https://www.uuidgenerator.net, or use the UUID from an existing user, which is accessible within the URL of the Jenkins console when managing an existing user's credentials.

    jenkins::credentials { 'deploy-user':
      password            => '',
      private_key_or_path => hiera('::deploy_key'),
      uuid                => hiera('::deploy_credentials_uuid'),

Configuring Security

The Jenkins security model can be set to one of two modes:

  • full_control - Users have full control after login. Authentication uses Jenkins' built-in user database.
  • unsecured - Authentication is not required.

Jenkins security is not managed by puppet unless jenkins::security is defined.

Using from Github / source

With librarian

If you use librarian-puppet, add the following to your Puppetfile:

mod "rtyler/jenkins"

With the "puppet module" tool

This module is compatible with the puppet module tool. Appropriately this module has been released to the Puppet Forge, allowing you to easily install the released version of the module

To quickly try this module with the puppet module tool:

% sudo puppet module install rtyler/jenkins
% sudo puppet apply -v -e 'include jenkins'
info: Loading facts in facter_dot_d
info: Loading facts in facter_dot_d
info: Applying configuration version '1323459431'
notice: /Stage[main]/Jenkins::Repo::El/Yumrepo[jenkins]/descr: descr changed '' to 'Jenkins'
notice: /Stage[main]/Jenkins::Repo::El/Yumrepo[jenkins]/baseurl: baseurl changed '' to 'http://pkg.jenkins-ci.org/redhat/'
notice: /Stage[main]/Jenkins::Repo::El/Yumrepo[jenkins]/gpgcheck: gpgcheck changed '' to '1'
notice: /Stage[main]/Jenkins::Repo::El/File[/etc/yum/jenkins-ci.org.key]/ensure: defined content as '{md5}9fa06089848262c5a6383ec27fdd2575'
notice: /Stage[main]/Jenkins::Repo::El/Exec[rpm --import /etc/yum/jenkins-ci.org.key]/returns: executed successfully
notice: /Stage[main]/Jenkins::Package/Package[jenkins]/ensure: created
notice: /Stage[main]/Jenkins::Service/Service[jenkins]/ensure: ensure changed 'stopped' to 'running'
notice: Finished catalog run in 27.46 seconds

Overriding the jenkins package name

It's possible to specify a different package name to the default jenkins if you wish:

class { 'jenkins':
  package_name => 'jenkins_custom',

Installing from a hosted RPM

Sometimes you don't have an RPM repository available and are not allowed to directly install from repositories on the Internet. In this case, you can still install Jenkins with this module by hosting the jenkins RPM file somewhere accessible (http server, S3 bucket, etc.) and tell

class { 'jenkins':
  direct_download => 'http://myserver/rpms/jenkins-x.xxx-1-1.rpm',