Jenkins Job Builder- A Hitchhiker’s Guide
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
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 -
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
“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”.
Click “Add new Token”, then on “Generate” and copy-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 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
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.
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.
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.
Block 4 : 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
- 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 -
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, publishers snapshots above.
Single Job Template 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 -
Job created in Jenkins -
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
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 -
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.
Reference Material
jenkins_job.ini and yamls used in the above examples can be found in the Git repository here.
