The Hitchhiker’s Guide  to  Jenkins Job Builder

Although the documentation for Jenkins Job Builder is very detailed, the step-by-step guide with examples for them is somehow missing. This was the main motivation for me to write this blog. 

Pre-Requisites

1. Pip
2. Git
3. An up-and-running Jenkins instance

Setting Up Jenkins Job Builder

Here, we will be walking through the steps needed for using the Jenkins Job Builder.

Step 1 — Clone the repository using the command below.

git clone https://git.openstack.org/openstack-infra/jenkins-job-builder

The cloned folder structure will be structured as in the snapshot below:

Step 2 — After cloning the repository, navigate to the folder “etc,” which consists of “.ini” sample file. Copy and paste that file and rename it to “jenkins_job.ini.”

Step 3 — Open the “jenkins_job.ini” and focus on the three parameters marked with a red star as in the snapshot below.

1. user — Jenkins user name
2. password — Jenkins password
3. url — Jenkins instance URL

“user” and “url” are pretty straight forward as the name suggests. However, the “password,” for the purpose of security, is not plain text and has to be an API token which can be used for making authenticated REST API or CLI calls.

To get the API token for the logged user, navigate to Jenkins > People > Your User > Configure, or directly navigate to the URL “http://<Your Domain>/user/<Your User>/configure” which in my case will be “http://localhost:8080/user/shreyas/configure”.

Click “Add new Token,” then on “Generate” and copy and paste the generated token against the password in the “jenkins_jobs.ini.”

Step 4 — Finally, the updated “.ini” file will look like the one below. Look at the updated 3 properties user, password, and URL.

For the purpose of this tutorial, we will keep the other parameters as the way they are. This is the generic configuration that needs to be done for using the Jenkins Job Builder.

Writing Jenkins Job Builder YAML

The next part of the configuration for using the Jenkins Job Builder is writing the YAML file. YAML files are the ones that are used for providing the configurations for creating the Jenkins jobs. There are two types of YAML that we will be looking at:

1. singlejob.yaml — Creates the job as per the configurations in the yaml
2. singlejobtemplate.yaml — Creates the job as per the job template. Can be reused for creating multiple jobs.
   
3. multiplejobtemplate.yaml — Creates multiple jobs all having the same configuration as per the job template. All the jobs will be created at one go.

Single Job Yaml

This YAML consists of 4 blocks.

The first is scm. This corresponds to the version control and its details we will be using in the Jenkins job. In the above example, it corresponds to Git version control, the URL, and the branch.

The second block is  builders. This corresponds to the build management tool, which is going to be used by the Jenkins job. In the above example, it corresponds to Maven, its version, pom.xml, and the Maven goals.

The third block is publishers. This corresponds to the artifact that will be generated to be published. In the above example, it will be any jar file that will be present in the path spring-boot-samples\spring-boot-sample-atmosphere\target.

On the fourth block are generic job details. This corresponds to the generic configuration details in the Jenkins job General tab.

Jenkins Job Creation Steps:

Step 1 — Verify configuration files

1. jenkins_jobs.ini in etc
2. singlejob.yaml in jobs

Step 2 — Execute the command below:

jenkins-jobs --conf etc/jenkins_jobs.ini update jobs/singlejob.yaml

Here are some things to note in the command above:

1. conf corresponds to the initialization file to be used by the Jenkins job builder, which in this case is jenkins_job.ini present in the etc folder.
2. update denotes the updation of the Jenkins job to be done using the singlejob.yaml present in the jobs folder.

Other configuration parameters can be referred here.

Command line output:

Job created in Jenkins:

Click on Configure in the left panel to view the 1-JJB-SimpleJob configuration details. The details of the job will be as in the general, scm, builders, and publishers snapshots above.

Single Job Template YAML

The fifth block is project. This corresponds to the name of the job that this YAML will take as an argument. Using this YAML, multiple jobs having the same configuration but different names can be created. The disadvantage is the command line will have to be run multiple times.

Command to execute:

jenkins-jobs --conf etc/jenkins_jobs.ini update jobs/singlejobtemplate.yaml

Command line output:

Job created in Jenkin:

Click on Configure in the left panel to view the 2-JJB-SimpleJob-Template configuration details. The details of the job will be viewable as in the general, scm, builders, publishers snapshots above.

Multiple Job Template YAML

Command to execute:

jenkins-jobs --conf etc/jenkins_jobs/jenkins_jobs.ini update jobs/multiplejobtemplate.yaml

Command line output:

Job created in Jenkins:

Click on Configure in the left panel to view the 3-JJB-Temp-1,3-JJB-Temp-2, 3-JJB-Temp-3 configuration details. The details of the job will be as in the general, scm, builders, publishers snapshots above.

jenkins_job.ini and yamls used in the above examples can be found in the Git repository here.