In this tutorial we will learn how to use Jenkins Job Builder to upload and maintain your Jenkins jobs using simple and human readable YAML or JSON files.

If you are using Jenkins, chances are that you are configuring them using its Web interface. While the Web interface of Jenkins can look quite simple for Desktop users, after a while it starts to become pretty tedious and error prone. Also, there is no immediate way to version control the Jenkins jobs when you are using the Web interface.

On the contrary, Jenkins Job Builder (JJB for short), uses simple human readable YAML or JSON files to generate Jenkins jobs which are uploaded to the Jenkins server.

Additionally, you can also create templates and macro and every file can be easily stored in your favorite version control system. Let's see how you can get started with Jenkins Job Builder:

To install Jenkins Job Builder you need to have Python available on your machine. You can install it as follows:

apt-get install python-pip

When pip is installed, it's time to install Jenkins Job Builder with:

pip install --user jenkins-job-builder

Configuring Jenkins Job Builder

The only configuration file required is jenkins_jobs.ini file which by default is searched in /etc/jenkins_jobs/jenkins_jobs.ini. You can however create it in any folder of your likes and use the --conf parameter to point to that file. So just create a file named jenkins_jobs.ini. Here is a sample content:


The most imporant attributes are the user and the hashed password. Let's see which value should we use in our configuration file. Start the Jenkins server first of all (see this tutorial to learn how to start Jenkins: Jenkins tutorial)

Now, once that you have logged in Jenkins, the following query will return your current user:


About the hashed password, the link to access your User's configuration is:


From there, browse to the API Token Section and click on the Show API Token button:

jenkins tutorial

Creating a Jenkins Job

Now it's time to start using Jenkins Job builder. Create a folder named "jobs" and inside that folder create a file named hello.yaml.

This is the hello.yaml which is nothing but a simple freestyle Jenkins job which fires a shell and prints a parameter from the job. Please mind it to copy the file exaclty as it is as YAML is rather strict on syntax so make sure you don’t miss anything!

- job:
    name: helloworld_job
      - string:
          name: message
          default: Hello World
    description: 'Automatically generated test'
    project-type: freestyle
      - shell: 'echo $message'

Execute the shell jenkins-job passing as parameter the configuration file, the command to execute (update) and the folder where jobs are contained:

$ jenkins-jobs --conf ./jenkins-jobs.ini update jobs
INFO:jenkins_jobs.cli.subcommand.update:Updating jobs in ['/home/jboss/jjb/jobs'] ([])
INFO:jenkins_jobs.builder:Number of jobs generated:  1
INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1):
INFO:jenkins_jobs.builder:Creating jenkins job helloworld_job
INFO:jenkins_jobs.cli.subcommand.update:Number of jobs updated: 1
INFO:jenkins_jobs.builder:Number of views generated:  0
INFO:jenkins_jobs.cli.subcommand.update:Number of views updated: 0

As a result the job has been uploaded on our Jenkins server. You can check it out from the Web interface:

Jenkins Job Builder tutorial

Let’s go ahead and create another yaml file in our jobs folder. We’ll name it defaults.yaml. For now, feel free to copy everything we have here, unless you know what settings you’d like to use.

Adding defaults

Defaults collect job attributes and will supply those values when the job is created, unless superseded by a value in the ‘Job’_ definition. We can specify them in a separate yaml file. Let's create a sample default.yaml file for this purpose:

- defaults:
    name: global
      daysToKeep: 10
      numToKeep: 10
      artifactDaysToKeep: -1
      artifactNumToKeep: -1

This configuration tells Jenkins that by default, we only want our jobs to keep our last 10 builds, for a maximum of 10 days, and that we’d like to save all artifacts indefinitely. Save the yaml file then rerun Jenkins-jobs update jobs.

That is just a first foray into the Jenkins Job Builder world. In the next tutorial (Using Templates in Jenkins Job Builder) we will learn how to use templates and macros to speedup your job creation.