⇑ Managing Jenkins Index

Configuring the System

Jenkins stores its global configuration in files on the Jenkins controller. Administrators and privileged users modify the global configuration from the Jenkins configuration pages.

Jenkins home directory

The JENKINS_HOME directory is the root of the directory structure on disk that Jenkins uses to perform builds and keep archives. The Jenkins home directory is listed in Manage Jenkins > System under the Home directory heading.

Home dir

  • On Windows by default, this is set to C:\ProgramData\Jenkins\.jenkins.

  • On Ubuntu by default, this is set to ~/.jenkins.

But you can change this in one of the following ways:

  • Set the JENKINS_HOME environment variable.

  • Set the JENKINS_HOME Java system property.

You can change this location after you’ve used Jenkins for a while, too. To do this:

  1. Stop Jenkins completely.

  2. Move the contents from the old JENKINS_HOME to the new location.

  3. Set the JENKINS_HOME variable to the new location.

  4. Restart Jenkins.

The directory structure of the JENKINS_HOME tree is often structured as follows:

JENKINS_HOME
 +- builds            (build records)
    +- [BUILD_ID]     (subdirectory for each build)
         +- build.xml      (build result summary)
         +- changelog.xml  (change log)
 +- config.xml         (Jenkins root configuration file)
 +- *.xml              (other site-wide configuration files)
 +- fingerprints       (stores fingerprint records, if any)
 +- identity.key.enc   (RSA key pair that identifies an instance)
 +- jobs               (root directory for all Jenkins jobs)
     +- [JOBNAME]      (sub directory for each job)
         +- config.xml (job configuration file)
     +- [FOLDERNAME]   (sub directory for each folder)
         +- config.xml (folder configuration file)
         +- jobs       (subdirectory for all nested jobs)
 +- plugins            (root directory for all Jenkins plugins)
     +- [PLUGIN]       (sub directory for each plugin)
     +- [PLUGIN].jpi   (.jpi or .hpi file for the plugin)
 +- secret.key         (deprecated key used for some plugins' secure operations)
 +- secret.key.not-so-secret  (used for validating _$JENKINS_HOME_ creation date)
 +- secrets            (root directory for the secret+key for credential decryption)
     +- hudson.util.Secret   (used for encrypting some Jenkins data)
     +- master.key           (used for encrypting the hudson.util.Secret key)
     +- InstanceIdentity.KEY (used to identity this instance)
 +- userContent        (files served under your https://server/userContent/)
 +- workspace          (working directory for the version control system)

Configuring the system page

The Configure System page (/manage/configure) allows administrators to configure global settings for the Jenkins controller. Below are the key sections available on this page:

System message

The system message is displayed at the top of every page in Jenkins. It can be used to communicate important information to all users, such as maintenance schedules or announcements.

Example:

The system is undergoing maintenance on YYYY-MM-DD.
Expect downtime.

Number of executors

The number of executors determines how many concurrent builds Jenkins can perform. For Jenkins controllers, it is recommended to set this to 0 to avoid resource contention. Executors should be configured on agents (nodes) instead.

Why set executors to 0 on the controller? Setting executors to 0 ensures that the controller is dedicated to managing builds and coordinating agents, rather than executing builds itself. This improves stability and performance.

For instance, agents with specific capabilities can be configured with multiple executors to handle concurrent builds effectively.

Labels

Labels are used to group agents (nodes) based on specific criteria. They help in assigning jobs to specific agents. For example, you can label agents based on their operating system or hardware capabilities.

Example:

linux, windows, docker, high-memory

Labels can be assigned in the agent configuration settings.

Usage

This section defines how jobs are assigned to agents. Options include:

  • Utilize this node as much as possible: Jobs will be assigned to this node whenever possible.

  • Only build jobs with label expressions matching this node: Jobs will only be assigned if their label matches.

Quiet period

The quiet period defines a delay before a build starts after a change is detected. This helps avoid triggering multiple builds for closely spaced changes.

Example:

Set a quiet period of 5 seconds to batch changes.

This is particularly useful for version control integrations, where commits may occur in quick succession.

Jenkins location

This section defines the URL of the Jenkins controller. It is important for proper communication with agents and external tools. If Jenkins is behind a reverse proxy, ensure the URL matches the proxy configuration.

For detailed instructions on configuring a reverse proxy, refer to the reverse proxy configuration guide.

Usage statistics

Jenkins collects anonymous usage statistics to help improve the software. This section allows you to opt-in or opt-out of this feature.

Plugin-specific configuration

Many plugins add their own global configuration options to the Configure System page. Since plugins extend Jenkins functionality, their settings often appear in this section and provide options for customization and fine-tuning. Refer to the online help for each plugin to understand these settings.

Tip: Use the question mark (?) icon next to each setting to access detailed help for that specific configuration.

Additional resources

⇑ Managing Jenkins Index

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.