Jenkins Job Builder- A Hitchhiker’s Guide
By: Shreyas Chaudhari
Tags: DevOps, Jenkins, Programming, Software Development, Continuous Integration

Clicked on the construction site next to my society in Pune, Maharashtra, India

On 16th March, I conducted a workshop in ThoughtWorks VodQA Pune on Jenkins — Pipeline As Code. In that workshop, I had conducted hands on exercises on Jenkins Job Builder. Post the completion of the workshop, number of folks walked up to me to thank me especially for conducting hands on for Jenkins Job Builder. On speaking to them, I realised that although the documentation for Jenkins Job Builder is very detailed, the step by step guide with examples for them are somehow missing. This was the main motivation for me to write this blog.

Pre-Requisites

Pip Git Up and Running Jenkins instance

Setting up Jenkins Job Builder

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

Step 1 — Clone the repository using the command below

Cloned folder structure will be as in the snapshot below -

Jenkins Job Builder Cloned Repository

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

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

user — Jenkins user name password — Jenkins password url — Jenkins instance url

jenkins_jobs.ini

“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 API token which can be used for making authenticated REST Api or CLI calls.

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

API Token

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

Post generating the Api token

Step 4 — Finally, the updated “.ini” file will look like the one below. Look at the 3 updated properties user, password, 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

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 2 types of yaml that we will be looking at -

singlejob.yaml — Creates the job as per the configurations in the yaml singlejobtemplate.yaml — Creates the job as per the job template. Can be reused for creating multiple jobs one at a time. 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

singlejob.yaml

The above yaml consists of 4 blocks -

Block 1 : 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.

scm block in the yaml which results in the above configuration in the Jenkins job

Block 2 : builders — This corresponds to the build management tool which are going to be used by the Jenkins job. In the above example, it corresponds to maven, its version, pom.xml and the maven goals.

builders block in the yaml which results in the above configuration in the Jenkins job

Block 3 : 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.

publishers block in the yaml which results in the above configuration in the Jenkins job

Block 4 : Generic job details — This corresponds to the generic configuration details in the Jenkins job General tab.

general configuration of the Jenkins job

Jenkins job creation steps -

Step 1 — Verify configuration files

jenkins_jobs.ini in etc singlejob.yaml in jobs

Step 2 — Execute the command below

Things to note in the command above -

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. 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 -

Jenkins job builder command execution logs

Job created in Jenkins -

Jenkins job 1-JJB-SimpleJob created

Click on 1-JJB-SimpleJob

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, publishers snapshots above.

Single Job Template Yaml

SingleJobTemplate.yaml

Block 5 : project — This corresponds to the name of the job that this yaml will take as an argument. Using this yaml, multiple jobs having same configuration but different names can be created. Disadvantage is the command line will have to be run multiple times.

Command to execute -

Command line output -

Jenkins job builder command execution logs

Job created in Jenkins -

Jenkins job 2-JJB-SimpleJob-Template created

Click on 2-JJB-SimpleJob-Template

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

Multiple Job Template Yaml

MultipleJobTemplate.yaml

Block 6: job-template — This corresponds to the name of the job template using which the further set of jobs will be created. Using this yaml, multiple jobs having same configuration but different names can be created by just running the command line once.

Command to execute -

Command line output -

Jenkins job builder command execution logs — 3 Jobs created

Job created in Jenkins -

Jenkins job 3-JJB-Temp-1, 3-JJB-Temp-2, 3-JJB-Temp-3 created

Click on of the 3 jobs created

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.

Clicked on the construction site next to my society in Pune, Maharashtra, India

Reference Material

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