Configuration as Code

The Jenkins Configuration as Code (JCasC) feature defines Jenkins configuration parameters in a human-readable YAML file that can be stored as source code. This essentially captures the configuration parameters and values that are used when configuring Jenkins from the web UI. The configuration can then be modified by editing this file and then applying it.

Traditionally, experienced Jenkins administrators created Apache Groovy init scripts to automate the configuration for their Jenkins instances. This works but requires in-depth understanding of Jenkins APIs and the ability to write Groovy scripts. Such scripts are powerful and can do almost anything, but they also provide few protections against configuration errors.

JCasC provides the convenience and flexibility of configuring controllers without using the UI. It does not require more understanding of the configuration parameters than is required to configure Jenkins through the UI and it provides some checks on the values that are provided.

The JCasC configuration file can be checked into an SCM, which enables you to determine who made what modifications to the configuration and to roll back to a previous configuration if necessary.

The Configuration as Code plugin must be installed on the Jenkins controller that you will use to build out your JCasC configuration. If you do not see the Configuration as Code tile in the System Configuration section of the Manage Jenkins page on your dashboard, you need to install the plugin.

Viewing the JCasC file

When the Configuration as Code plugin is installed, you will see Configuration as Code in the System Configuration section of the Manage Jenkins page on your dashboard. Click on this link, then click on View Configuration to view the YAML file.

This file is an export of the current configuration on this controller. In most cases, it is ready to use without modification although you usually want to customize it before deploying it. You may want to push the unmodified version to SCM so you have it as part of your history.

The Configuration as Code UI page shows the full pathname of the YAML file being used and gives a box where you can specify a different file to use. See the information below about how to modify the location used for JCasC YAML files.

The default JCasC YAML file has four sections:

  • jenkins section defines the root Jenkins object, with configurations that can be set with the Manage Jenkins >> Configure System and Manage Jenkins >> Configure Nodes and Clouds screens.

  • tool section defines build tools that can be set on the Manage Jenkins >> Global Tool Configuration screen.

  • unclassified section defines all other configurations, including configuration for installed plugins.

  • credentials section defines credentials that can be set on the Manage Jenkins >> Manage Credentials screen. You may want to delete this section from your YAML file; this is discussed in How to Install Jenkins on CentOS 7 Using Ansible and JCasC.

YAML file syntax

JCasC defines the controller configuration in a YAML file. YAML is a popular serialization language for configuration information, with a syntax that is straight-forward and easy to read but precise.

Some key points about YAML syntax:

  • YAML files are case sensitive.

  • Indentation is very significant and specific.

  • Each item is a key/value pair.

    • The key is followed by a colon (:) and a space.

    • YAML converts certain strings into other types unless they are in quotes.

      • Values such as true, false, Yes, and No are converted to Boolean values.

      • Values such as 2 and 3.0 are converted to floating point values.

  • A value can be a list:

    • Each list item is on a separate line starting with a dash (-).

    • Each list item in the file must start at the same indentation.

      • Use spaces, never tabs, for indentation.

    • Never leave a blank line in a YAML file — things will break!

See the YAML Reference Card for more details about YAML file syntax.

Checking the YAML files into SCM

To get the maximum benefit of JCasC, the YAML files should be stored in SCM. This gives you a history that you can use to trace changes that are made and allow you to easily roll back to an earlier version of the file if necessary.

JCasC does not require that the file be stored in SCM and so does not enforce any rules about how you do this. The most common practice is to create one SCM repository in which you store all of your JCasC files.

If you are storing your JCasC YAML files in SCM, you should commit the first default file that is generated, before you make any modifications to the file.

Modifying the JCasC file

To modify the JCasC YAML file, use the text editor of your choice to edit the file that is listed on the Manage Jenkins >> Configuration as Code UI page. By default, this is $JENKINS_HOME/jenkins.yaml.

For a simple exercise to work through the process, you can modify the value of the "System Message" that is displayed on the Jenkins dashboard.

  1. Open the JCasC YAML file with the text editor of your choice.

  2. Find the systemMessage line near the top of the file:

    jenkins:
  systemMessage: "Jenkins configured automatically by Jenkins Configuration as Code plugin\n\n"

  3. Modify the text between the quotation marks to contain your new text

  4. Write/save the file

  5. Click the Reload existing configuration button to apply the changes

  6. View the modified "System Message" on your dashboard

It is not necessary to restart Jenkins to apply the JCasC changes, although you should try to restart Jenkins with the modifications before you check the modified YAML file into SCM, especially when making more substantive configuration changes.

When you have made and tested your desired changes, push the modified JCasC YAML file to your SCM.

Configuring a plugin with JCasC

To configure a plugin with JCasC:

  1. Use the UI of the current system to install and configure the plugin

  2. Click Apply >> Save to save the configuration

  3. Use Manage Jenkins >> Configuration as Code >> View Configuration to view the JCasC file with the plugin configured

  4. Click on Download Configuration to save the modified configuration file locally

  5. Edit the JCasC YAML file to modify the configuration, if necessary

  6. Save the file

  7. Click Reload existing configuration to load the local changes onto the Jenkins server

  8. Verify the changes on the UI

  9. When you have thoroughly tested the plugin configuration, push the modified YAML file to your SCM

See the Configure Plugins with JCasC blog for detailed instructions and an embedded video demonstration of this process.

YAML file location

By default, the YAML file for the CasC configuration is located in $JENKINS_HOME/jenkins.yaml. The location and name of the file being used is displayed on the Configuration as Code UI page. You can specify a different file to view by typing the full pathname into the Path or URL field.

You can specify a different location or a different file name for the creation of the JCasC YAML file by doing either of the following:

  • Populate the CASC_JENKINS_CONFIG environment variable to point to a comma-separated list that defines where configuration files are located.

  • Use the casc.jenkins.config Java property to control the file name and location. This is useful when installing Jenkins via a package management tool. Most package management systems support configuration files that are retained across upgrades. It is best to not modify a file installed by a package manager because it could be overwritten by an update.

    On Linux systems, you can run systemctl edit jenkins and add the following:

    [Service]
Environment="JAVA_OPTS=-Dcasc.jenkins.config=/jenkins/casc_configs"

The file location and name can be specified as any of the following:

  • Path to a folder containing a set of config files such as /var/jenkins_home/casc_configs.

  • A full path to a single file such as /var/jenkins_home/casc_configs/jenkins.yaml.

  • A URL pointing to a file served on the web such as https://acme.org/jenkins.yaml.

The value of the CASC_JENKINS_CONFIG variable is unpacked according to the following rules:

  • If an element of CASC_JENKINS_CONFIG points to a folder, the plugin recursively traverses the folder to find file(s) with the .yml, .yaml, .YAML, or .YML suffix.

  • It excludes hidden files or files that contain a hidden folder (such as/ jenkins/casc_configs/.dir1/config.yaml) in any part of the full path.

  • It follows symbolic links for both files and directories.

  • The order of traversal does not matter to the final outcome because all configuration files that are discovered MUST be supplementary. If a file attempts to overwrite configuration values from another file, it creates a conflict and raises a ConfiguratorException.

CasC configuration and UI modifications

Configuration for a Jenkins controller should be implemented either with CasC or with the UI, but not by both. The system allows administrators to modify configuration options on the UI even when they were configured by CasC, but these modifications are overwritten the next time the controller restarts.

You can install the Extended Read Permission Plugin, which allows you to grant read-only access to configuration parameters to users. See JEP-224: Readonly system configuration for more details.

A small group of administrators may have write access to the UI configuration fields. They should understand that JCasC will overwrite changes they make on the UI.

For more information

General information

Implementation details

Much of the detailed JCasC documentation is provided in the Github repository.

Information for plugin developers and maintainers