Configure Plugins with JCasC

Published on 2021-05-20 by Dheeraj Singh Jodha

This blog post is for anyone interested to know how to configure a plugin using the Jenkins Configuration as a Code (JCasC) plugin, more specifically, this blog will guide you to get the YAML equivalent of a plugin’s configuration and use it to do some changes to the plugin without using the Jenkins UI.

If you’re a beginner at JCasC and want to learn more about it, you can head over to the following resources to understand JCasC better:

Configuring your first plugin using JCasC (Video Demo)

Overview

So, these are the steps we will be following to achieve our aim:

  1. Brief Introduction to jenkins.yaml file

  2. Configure the plugin on the UI

  3. Download the Configuration

  4. Update JCasC file locally

  5. Load the jenkins.yaml file on the Jenkins server

  6. Verify the changes on the UI

Brief Introduction to jenkins.yaml file

  • The jenkins.yaml file contains the configuration of the Jenkins instance in YAML format. The JCasC plugin refers to this file to configure the Jenkins instance.

  • The default location of jenkins.yaml is $JENKINS_HOME/jenkins.yaml, from where it can be fetched into the Jenkins server whenever you apply a new configuration.

  • Download your jenkins.yaml file by going to Manage Jenkins > Configuration as Code > Download Configuration.

  • Make sure this file is saved at location $JENKINS_HOME/jenkins.yaml.

  • Let’s change the systemMessage field to:

Updating the jenkins.yaml file
Figure 1. Updating the jenkins.yaml file

  • Reload the existing configuration to apply the system message change

  • Now, go back to the Dashboard and you can see the updated System Message on top:

Viewing the changes
Figure 2. Viewing the changes on Dashboard

  • This file will be used later to configure the plugin using JCasC.

Configure the plugin on the UI

  • For this demo, install the View Job Filters plugin.

  • Let’s create a view by clicking on the New View option on the left side of the Dashboard.

  • Give it a name (say, “testView”) and set its type to List View, and click on the OK button.

Naming the View
Figure 3. Creating the View

  • Now click on Add Job Filter to add any kind of filter, so let’s select Build Duration Filter and fill the field with any value (say, "60" minutes),

Add Filters
Figure 4. Adding filter to the view

  • Click on Apply > Save.

  • To view the full configuration, check out your main jenkins.yaml configuration file, by clicking on Manage Jenkins > Configuration as Code > View Configuration

  • Go to the views section in this YAML file to see details related to the view,

YAML file on Jenkins UI
Figure 5. Here, details regarding the view (which we just created) is visible

Download the Configuration

  • Now that you have successfully configured your plugin by UI, let’s download the configuration by going to Manage Jenkins on the Dashboard, then click on Configuration as Code under "System Configuration".

  • Now click on the Download Configuration button to save the configuration file locally.

Download Configuration
Figure 6. Downloading the Configuration

Update JCasC file locally

  • Add some changes in your downloaded copy of the jenkins.yaml file, to see those changes being automatically reflected on the UI.

  • For demo purposes, let’s change the name to “YoutubeDemoView” and set the buildDurationMinutes as "55".

YAML file on Text Editor
Figure 7. Changing the View details locally

  • Save the file.

Load the jenkins.yaml file on the Jenkins server

  • Now to reflect the local changes done in the jenkins.yaml file onto the Jenkins server, click on the Reload existing configuration button.

Apply New Configuration
Figure 8. Applying the New Configuration to the Jenkins instance

Verify the changes on the UI

  • Go back to the main page by clicking on the Jenkins logo on the top-left side.

  • And you will notice that the name of your view has been changed from "testView" to “YoutubeDemoView”,

  • And the field value of Build Duration Filter has been changed from "60" to “55”.

  • These two are the exact changes that we did locally in our jenkins.yaml file.

View Updated Changes
Figure 9. Verifying the changes

Congratulations! You’ve successfully configured a plugin (“View Job Filter”) automatically with the help of the “Jenkins Configuration as Code” plugin! You can repeat the same process for other plugins as well.

About the Author
Dheeraj Singh Jodha

Dheeraj is a Computer Science Engineering student (senior) at Vivekanand Institute of Technology, University of Mumbai. He started his journey of contributing to Jenkins in March 2021. His tiny contributions revolve around the Custom Distribution Service for Jenkins Project. He also likes to contribute to the JCasC project and documentation to help the developers.