Blog
Token
About Us
AiDOOS Wiki
Project Cost Estimation

Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Categories
All
CRM
Salesforce
ERP
SAP
Storage and Backups
Purestorage Netapp Nutanix
Cloud
AWS
Computing
IBM
Database
MongoDB MySQL PostgreSQL
DevOps
Docker Kubernetes Jenkins GitLab
Mobile
React Native Android
Web
React Angular PHP
Programming
Python
DevOps-Jenkins
Other Servlet Containers

Other Servlet Containers

Table of Contents
  • Tomcat 9
  • WildFly 26

Jenkins is typically run as a standalone application in its own process. The Jenkins WAR file bundles Winstone, a Jetty servlet container wrapper, and can be started on any operating system or platform with a version of Java supported by Jenkins. This is the preferred way to deploy Jenkins and is fully supported.

Theoretically, Jenkins can also be run as a servlet in a traditional servlet container like Apache Tomcat or WildFly, but in practice this is largely untested and there are many caveats. In particular, support for WebSocket agents is only implemented for the Jetty servlet container. See the Servlet Container Support Policy page for details.

Support for traditional servlet containers may be discontinued in the future.

Jenkins requires Servlet API 4.0 (Jakarta EE 8) with javax.servlet imports. Jenkins is incompatible with Servlet API 5.0 (Jakarta EE 9) or later with jakarta.servlet imports. Ensure that the Servlet API version of your chosen servlet container is compatible before running Jenkins.

Tomcat 9

Tomcat 9 is based on Servlet API 4.0 (Jakarta EE 8), which is the version of the servlet API required by Jenkins.

Later versions of Tomcat use newer versions of the Servlet API and are incompatible with Jenkins.

Jenkins can be deployed to Tomcat by placing the Jenkins WAR file in the ${CATALINA_HOME}/webapps/ directory.

To configure the Jenkins home directory, set the JENKINS_HOME Java system property via the CATALINA_OPTS environment variable. For example, create ${CATALINA_HOME}/bin/setenv.sh with the following contents: 

export CATALINA_OPTS=-DJENKINS_HOME=/var/lib/jenkins
Running multiple Jenkins controllers within a single Java process is unsupported.

Scheme selection in redirect URLs is delegated to the servlet container, and Jetty handles the X-Forwarded-For , X-Forwarded-By , and X-Forwarded-Proto headers by default. With Tomcat, one needs to add a Remote IP Valve to expose these headers to Jenkins via the Servlet API. Add the following to ${CATALINA_HOME}/conf/server.xml within the <Host> section: 

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="X-Forwarded-For"
       proxiesHeader="X-Forwarded-By"
       protocolHeader="X-Forwarded-Proto" />

WildFly 26

WildFly 26 is based on Servlet API 4.0 (Jakarta EE 8), which is the version of the servlet API required by Jenkins.

Later versions of WildFly use newer versions of the Servlet API and are incompatible with Jenkins.

Jenkins can be deployed to WildFly by placing the Jenkins WAR file in the ${JBOSS_HOME}/standalone/deployments/ directory.

To configure the Jenkins home directory, set the JENKINS_HOME Java system property via the JAVA_OPTS environment variable. For example, update ${JBOSS_HOME}/bin/standalone.conf with the following contents: 

JAVA_OPTS="$JAVA_OPTS -DJENKINS_HOME=/var/lib/jenkins"
Running multiple Jenkins controllers within a single Java process is unsupported.

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?


See existing feedback here.

WAR file

WAR file

Table of Contents
  • Prerequisites
  • Run the WAR file
  • Post-installation setup wizard
    • Unlocking Jenkins
    • Customizing Jenkins with plugins
    • Creating the first administrator user

The Jenkins Web application ARchive (WAR) file bundles Winstone, a Jetty servlet container wrapper, and can be started on any operating system or platform with a version of Java supported by Jenkins. See the Java Requirements page for details.

Prerequisites

Minimum hardware requirements:

  • 256 MB of RAM

  • 1 GB of drive space (although 10 GB is a recommended minimum if running Jenkins as a Docker container)

Recommended hardware configuration for a small team:

  • 4 GB+ of RAM

  • 50 GB+ of drive space

Comprehensive hardware recommendations:

  • Hardware: see the Hardware Recommendations page

Software requirements:

  • Java: see the Java Requirements page

  • Web browser: see the Web Browser Compatibility page

  • For Windows operating system: Windows Support Policy

  • For Linux operating system: Linux Support Policy

  • For servlet containers: Servlet Container Support Policy

Run the WAR file

The Jenkins Web application ARchive (WAR) file can be started from the command line like this:

  1. Download the latest Jenkins WAR file to an appropriate directory on your machine

  2. Open up a terminal/command prompt window to the download directory

  3. Run the command java -jar jenkins.war

  4. Browse to http://localhost:8080 and wait until the Unlock Jenkins page appears

  5. Continue on with the Post-installation setup wizard below

Notes:

  • This process does not automatically install any specific plugins. They need to installed separately via the Manage Jenkins > Manage Plugins page in Jenkins.

  • You can change the port by specifying the --httpPort option when you run the java -jar jenkins.war command. For example, to make Jenkins accessible through port 9090, then run Jenkins using the command:
    java -jar jenkins.war --httpPort=9090

  • You can change the directory where Jenkins stores its configuration with the JENKINS_HOME environment variable. For example, to place the Jenkins configuration files in a subdirectory named my-jenkins-config , define JENKINS_HOME=my-jenkins-config before running the java -jar jenkins.war command. Use the Windows commands:

    Windows 
    C:\Temp > set JENKINS_HOME=my-jenkins-config
C:\Temp > java -jar jenkins.war

    or the Unix command:

    Unix 
    $ JENKINS_HOME=my-jenkins-config java -jar jenkins.war

For more details of command line arguments that can adjust Jenkins startup, use the command:
java -jar jenkins.war --help

Post-installation setup wizard

After downloading, installing and running Jenkins using one of the procedures above (except for installation with Jenkins Operator), the post-installation setup wizard begins.

This setup wizard takes you through a few quick "one-off" steps to unlock Jenkins, customize it with plugins and create the first administrator user through which you can continue accessing Jenkins.

Unlocking Jenkins

When you first access a new Jenkins instance, you are asked to unlock it using an automatically-generated password.

  1. Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.

    Unlock Jenkins page

  2. From the Jenkins console log output, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).

    Copying initial admin password
    Note:

    • The command: sudo cat /var/lib/jenkins/secrets/initialAdminPassword will print the password at console.

    • If you are running Jenkins in Docker using the official jenkins/jenkins image you can use sudo docker exec ${CONTAINER_ID or CONTAINER_NAME} cat /var/jenkins_home/secrets/initialAdminPassword to print the password in the console without having to exec into the container.

  3. On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue .
    Notes:

    • You can always access the Jenkins console log from the Docker logs (above).

    • The Jenkins console log indicates the location (in the Jenkins home directory) where this password can also be obtained. This password must be entered in the setup wizard on new Jenkins installations before you can access Jenkins’s main UI. This password also serves as the default administrator account’s password (with username "admin") if you happen to skip the subsequent user-creation step in the setup wizard.

Customizing Jenkins with plugins

After unlocking Jenkins, the Customize Jenkins page appears. Here you can install any number of useful plugins as part of your initial setup.

Click one of the two options shown:

  • Install suggested plugins - to install the recommended set of plugins, which are based on most common use cases.

  • Select plugins to install - to choose which set of plugins to initially install. When you first access the plugin selection page, the suggested plugins are selected by default.

If you are not sure what plugins you need, choose Install suggested plugins . You can install (or remove) additional Jenkins plugins at a later point in time via the Manage Jenkins > Manage Plugins page in Jenkins.

The setup wizard shows the progression of Jenkins being configured and your chosen set of Jenkins plugins being installed. This process may take a few minutes.

Creating the first administrator user

Finally, after customizing Jenkins with plugins , Jenkins asks you to create your first administrator user.

  1. When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish .

  2. When the Jenkins is ready page appears, click Start using Jenkins .
    Notes:

    • This page may indicate Jenkins is almost ready! instead and if so, click Restart .

    • If the page does not automatically refresh after a minute, use your web browser to refresh the page manually.

  3. If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?


See existing feedback here.

Read article
Windows

Windows

Table of Contents
  • Prerequisites
  • Installation steps using Windows MSI installer
  • Silent Install with the MSI installers
  • Post-installation setup wizard
    • Unlocking Jenkins
    • Customizing Jenkins with plugins
    • Creating the first administrator user
  • Troubleshooting Windows installation
    • Invalid service logon credentials

The simplest way to install Jenkins on Windows is to use the Jenkins Windows installer. That program will install Jenkins as a service using a 64 bit JVM chosen by the user. Keep in mind that to run Jenkins as a service, the account that runs Jenkins must have permission to login as a service.

Prerequisites

Minimum hardware requirements:

  • 256 MB of RAM

  • 1 GB of drive space (although 10 GB is a recommended minimum if running Jenkins as a Docker container)

Recommended hardware configuration for a small team:

  • 4 GB+ of RAM

  • 50 GB+ of drive space

Comprehensive hardware recommendations:

  • Hardware: see the Hardware Recommendations page

Software requirements:

  • Java: see the Java Requirements page

  • Web browser: see the Web Browser Compatibility page

  • For Windows operating system: Windows Support Policy

  • For Linux operating system: Linux Support Policy

  • For servlet containers: Servlet Container Support Policy

Installation steps using Windows MSI installer

How to install Jenkins on Windows

Refer to the Windows section of the Downloading Jenkins page to download either an LTS release or a weekly release of the Windows installer. After the download completes, open the Windows installer and follow the steps below to install Jenkins.

Step 1: Setup wizard

On opening the Windows Installer, an Installation Setup Wizard appears, Click Next on the Setup Wizard to start your installation.

Windows Installation Setup Wizard

Step 2: Select destination folder

Select the destination folder to store your Jenkins Installation and click Next to continue.

Jenkins Installation Destination

Step 3: Service logon credentials

When Installing Jenkins, it is recommended to install and run Jenkins as an independent windows service using a local or domain user as it is much safer than running Jenkins using LocalSystem(Windows equivalent of root) which will grant Jenkins full access to your machine and services.

To run Jenkins service using a local or domain user , specify the domain user name and password with which you want to run Jenkins, click on Test Credentials to test your domain credentials and click on Next .

Jenkins Service Logon Credentials

If you get Invalid Logon Error pop-up while trying to test your credentials, follow the steps explained here to resolve it.
Step 4: Port selection

Specify the port on which Jenkins will be running, Test Port button to validate whether the specified port if free on your machine or not. Consequently, if the port is free, it will show a green tick mark as shown below, then click on Next .

Jenkins Select Port

Step 5: Select Java home directory

The installation process checks for Java on your machine and prefills the dialog with the Java home directory. If the needed Java version is not installed on your machine, you will be prompted to install it.

Once your Java home directory has been selected, click on Next to continue.

Select Java Home Directory

Step 6: Custom setup

Select other services that need to be installed with Jenkins and click on Next .

Jenkins Custom Setup

Step 7: Install Jenkins

Click on the Install button to start the installation of Jenkins.

Windows Install Jenkins

Additionally, clicking on the Install button will show the progress bar of installation, as shown below:

Windows Installation Progress

Step 8: Finish Jenkins installation

Once the installation completes, click on Finish to complete the installation.

Jenkins will be installed as a Windows Service . You can validate this by browsing the services section, as shown below:

Windows Jenkins Service

See the upgrade steps when you upgrade to a new release.

Silent Install with the MSI installers

MSI installers can be installed via a silent method, which can show basic UI (/qb) or no UI at all (/qn). The silent method does not prompt for user input so there are properties that you can pass to the installer to set the specific values. A very basic command line is shown below for a silent install. 

msiexec.exe /i "path\to\jenkins.msi" /qn /norestart
This will use all of the default values for things that would normally be a prompt such as:

  • Installation directory

  • Service account username/password

  • Java installation directory

  • The port for Jenkins to listen on

Each of these things can be overridden by passing a NAME=VALUE property pair for what you want to override:

Property Name Description

INSTALLDIR

Path to the directory to install Jenkins. (Default: C:\Program Files\Jenkins)

PORT

The port Jenkins will listen on. (Default: 8080)

JAVA_HOME

The directory where java.exe can be found. (Default: The first Java runtime found in the registry with Java 11 being higher priority than Java 17)

SERVICE_USERNAME

The username that the service should run as. The account must have LogonAsService permissions. (Default: In silent mode, the LOCALSYSTEM account)

SERVICE_PASSWORD

The password for the SERVICE_USERNAME account. This should only be provided if SERVICE_USERNAME is provided. (Default: In silent mode, none for LOCALSYSTEM)

A more complex example, including the creation of a log file for the installation process is shown below: 

msiexec.exe /i "path\to\jenkins.msi" /qn /norestart INSTALLDIR="D:\Jenkins" JAVA_HOME="C:\Program Files\SomeJava" PORT=80 /L*v "path\to\logfile.txt"

This would install Jenkins into D:\Jenkins, use the Java runtime from C:\Program Files\SomeJava and Jenkins would be listening on port 80.

Post-installation setup wizard

After downloading, installing and running Jenkins, the post-installation setup wizard begins.

This setup wizard takes you through a few quick "one-off" steps to unlock Jenkins, customize it with plugins and create the first administrator user through which you can continue accessing Jenkins.

Unlocking Jenkins

When you first access a new Jenkins instance, you are asked to unlock it using an automatically-generated password.

Step 1

Browse to http://localhost:8080 (or whichever port you configured for Jenkins when installing it) and wait until the Unlock Jenkins page appears.

Unlock Jenkins page

Step 2

The initial Administrator password should be found under the Jenkins installation path (set at Step 2 in Jenkins Installation).

For default installation location to C:\Program Files\Jenkins, a file called initialAdminPassword can be found under C:\Program Files\Jenkins\secrets.

However, If a custom path for Jenkins installation was selected, then you should check that location for initialAdminPassword file.

Jenkins Initial Password Location

Step 3

Open the highlighted file and copy the content of the initialAdminPassword file.

Jenkins Initial Password File

Step 4

On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue .
Notes:

  • You can also access Jenkins logs in the jenkins.err.log file in your Jenkins directory specified during the installation.

  • The Jenkins log file is another location (in the Jenkins home directory) where the initial password can also be obtained. Windows Jenkins Log File This password must be entered in the setup wizard on new Jenkins installations before you can access Jenkins’s main UI. This password also serves as the default administrator account’s password (with username "admin") if you happen to skip the subsequent user-creation step in the setup wizard.

Customizing Jenkins with plugins

After unlocking Jenkins, the Customize Jenkins page appears. Here you can install any number of useful plugins as part of your initial setup.

Click one of the two options shown:

  • Install suggested plugins - to install the recommended set of plugins, which are based on most common use cases.

  • Select plugins to install - to choose which set of plugins to initially install. When you first access the plugin selection page, the suggested plugins are selected by default.

If you are not sure what plugins you need, choose Install suggested plugins . You can install (or remove) additional Jenkins plugins at a later point in time via the Manage Jenkins > Manage Plugins page in Jenkins.

The setup wizard shows the progression of Jenkins being configured and your chosen set of Jenkins plugins being installed. This process may take a few minutes.

Creating the first administrator user

Finally, after customizing Jenkins with plugins , Jenkins asks you to create your first administrator user.

  1. When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish .

  2. When the Jenkins is ready page appears, click Start using Jenkins .
    Notes:

    • This page may indicate Jenkins is almost ready! instead and if so, click Restart .

    • If the page does not automatically refresh after a minute, use your web browser to refresh the page manually.

  3. If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

Troubleshooting Windows installation

Invalid service logon credentials

Invalid Service Logon Credentials

When installing a service to run under a domain user account, the account must have the right to logon as a service. This logon permission applies strictly to the local computer and must be granted in the Local Security Policy.

Perform the following steps below to edit the Local Security Policy of the computer you want to define the ‘logon as a service’ permission:

  1. Logon to the computer with administrative privileges.

  2. Open the Administrative Tools and open the Local Security Policy

  3. If the Local Security Policy is missing in your system, refer to the answer in the Where to download GPEdit.msc for Windows 10 Home? question on Microsoft Community to troubleshoot

  4. Expand Local Policy and click on User Rights Assignment

  5. In the right pane, right-click Log on as a service and select properties.

  6. Click on the Add User or Group… button to add the new user.

  7. In the Select Users or Groups dialogue, find the user you wish to enter and click OK

  8. Click OK in the Log on as a service Properties to save changes.

After completing the steps above, try logging in again with the added user.

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?


See existing feedback here.

Read article
About Jenkins

About Jenkins

The Manage Jenkins >> About Jenkins page shows the current release of Jenkins on your system plus information about licenses for all components. The top of the display shows the release and version of Jenkins that is running.

The following information about your Jenkins cluster is also provided:

  • List of all third-party libraries used for this release of Jenkins, with links to licensing details about each library.

  • List of static resources that are installed.

  • List of installed plugins, each of which includes a link to the page that shows all third-party dependencies for each plugin with a link to licensing details about each library.

This video shares different methods to check the version of Jenkins being used.

What is the latest version of Jenkins?

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?


See existing feedback here.

Read article
Built-In Node Name and Label Migration

Built-In Node Name and Label Migration

As part of the terminology cleanup effort, the built-in node was renamed from "master node" to "built-in node" in Jenkins 2.307 and in Jenkins 2.319.1. This is not just a change affecting the UI and documentation: The node name affects the implicitly assigned label of the node (and consequently the NODE_LABELS environment variable), as well as the NODE_NAME environment variable.

The NODE_NAME environment variable in Pipelines is set by the Pipeline: Nodes and Processes plugin. In plugin version 2.39 and earlier, this value is always master . Update to version 2.40 or newer to get consistent behavior between job types.

Affected Features

Jenkins features using node labels are therefore potentially impacted by any such changes. These features include:

  • Label assignments of various project types, both on the top level (e.g. Freestyle jobs) and within jobs (e.g. node statements in Scripted Pipeline, label parameters to agent sections in Declarative Pipeline, or Matrix Project axes).

  • Label assignments of features like custom tool auto-installers, typically used to distinguish OS platforms.

  • Any custom build scripts whose behavior is different based on the NODE_NAME or NODE_LABELS environment variables (or their env global variable equivalent in Pipeline).

  • Any similar features in plugins.

Migration

Due to the potential impact to build behavior, instances upgrading Jenkins to version 2.307 or newer do not automatically get these behavior changes applied. Instead, an administrative monitor informs administrators about this change and allows them to apply it.

Before applying the built-in node name and label migration, administrators are advised to review their configuration and build scripts to assess the impact to their instance and jobs.

Most problems with label assignments can likely be worked around by manually assigning the label master to the built-in node and then migrating affected configuration incrementally to not need this workaround.

Plugin Compatibility

Known Incompatible Plugins

  • Pipeline: Nodes and Processes always sets the NODE_NAME to master in Pipelines before version 2.40.

  • Node and Label Parameter plugin displays the controller node as master in releases before version 1.10.0.

Use this Jira query to find compatibility issues tracked in the Jenkins Jira.

Use this GitHub query to find compatibility issues tracked on GitHub.

Reporting Incompatible Plugins

Please report problems in the respective plugin’s issue tracker.

If the affected plugin uses the Jenkins Jira to track issues, please add the label built-in-node-migration-regression .

If the affected plugin tracks issues on GitHub, please make sure to mention the Jenkins pull request that implemented the change in your issue.

Read article
Configuration as Code

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

  • Look Ma! No Hands! — Manage Jenkins Configuration as Code is a video of the 2018 DevOps World presentation that introduced the JCasC feature.

  • Configure Plugins with JCasC is a blog post with video that demonstrates how to configure a plugin with JCasC.

  • How to Install Jenkins on CentOS 7 Using Ansible and JCasC is a video presentation with details about using JCasc.

Implementation details

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

  • Implementation details

    • The demos directory contains sample *.yaml files for configuring specific Jenkins components and plugins, with a README file in each directory that describes the configurations for that component.

    • How to create the initial "seed" job with Job DSL

    • Usage scenarios

    • Triggering Configuration Reload

    • Exporting configurations

Information for plugin developers and maintainers

  • Developer documentation for JCasC

  • JCasC Requirements - guide for plugin maintainers

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?


See existing feedback here.

Read article