Jenkins - Configuration
Jenkins - System Configuration
Section titled “Jenkins - System Configuration”Global configuration settings for your Jenkins instance are managed primarily under Manage Jenkins → System. This is where you define system-wide behaviors, tool locations, and integrations.
Key Configuration Sections
Section titled “Key Configuration Sections”Jenkins Location
Section titled “Jenkins Location”- Jenkins URL: The root URL for your Jenkins instance (e.g.,
https://jenkins.example.com/). This must be set correctly for links in notifications, webhooks, and other integrations to work properly. Jenkins often auto-detects this, but verify it, especially if behind a reverse proxy. - System Admin e-mail address: An email address for Jenkins to send administrative notifications to (e.g., warnings about low disk space if configured). Also used as the default ‘From’ address for basic email notifications.
Home directory
Section titled “Home directory”Displays the path to JENKINS_HOME, where Jenkins stores all its data (jobs, builds, plugins, system config). While displayed here, changing it typically requires setting the JENKINS_HOME environment variable or Java system property before starting Jenkins, or modifying the service configuration file.
Ensuring JENKINS_HOME resides on a partition with ample disk space and good I/O performance (SSD recommended) is crucial.
Agent (Node) Monitoring
Section titled “Agent (Node) Monitoring”Configure how Jenkins monitors the health of connected agents (e.g., checking clock differences, responding to pings).
# of executors
Section titled “# of executors”Defines the number of concurrent builds that can run directly on the Jenkins controller machine. It is strongly recommended to set this to 0 or 1. The controller should focus on orchestrating builds, not executing them. Offload builds to agents (see ‘Distributed Builds’ chapter).
Labels
Section titled “Labels”View and manage labels assigned to the controller node itself.
Control how jobs are assigned to the controller (usually set to ‘Only build jobs with label expressions matching this node’ and use specific labels if the controller must run certain light tasks).
Quiet period
Section titled “Quiet period”The number of seconds Jenkins waits after a commit is detected before starting a build. Useful to allow multiple related commits to be processed in a single build.
SCM checkout retry count
Section titled “SCM checkout retry count”How many times Jenkins should retry checking out source code if it fails.
Global properties
Section titled “Global properties”- Environment variables: Define key-value pairs that will be available as environment variables to all builds running on Jenkins. Useful for setting global paths or configuration values.
- Tool Locations: Add paths to tools installed on the controller/agents that are not managed by Global Tool Configuration auto-installers. Useful if you need specific versions or tools not covered there.
Jenkins CLI
Section titled “Jenkins CLI”Configure options for the Jenkins Command Line Interface, such as the transport protocol (HTTP, SSH).
E-mail Notification
Section titled “E-mail Notification”Configure the global SMTP server settings for the basic built-in email notifications. Enter your SMTP server hostname, port, default user email suffix, and authentication details if required. Click ‘Test configuration’ to verify.
Note: For advanced email features (templates, triggers, attachments), install and configure the ‘Email Extension’ plugin instead of or in addition to this section.
Other Plugin Configurations
Section titled “Other Plugin Configurations”Many installed plugins add their global configuration sections here. Examples include settings for Git, Maven, Gradle, Docker, Kubernetes, cloud providers (AWS, Azure, GCP), security realms (LDAP, SAML), notification services (Slack, Teams), artifact repositories (Nexus, Artifactory), etc.
Global Tool Configuration
Section titled “Global Tool Configuration”Accessed via Manage Jenkins → Global Tool Configuration, this section focuses specifically on managing build tool installations (JDK, Maven, Gradle, Git, NodeJS, etc.). For each tool, you can:
- Add multiple named installations: (e.g., JDK 11, JDK 17).
- Specify path: Point to a pre-installed tool location via
*_HOME. - Enable automatic installation: Have Jenkins download and install specific tool versions automatically. This is useful for ensuring consistent tool versions across different agents without manual installation.
Pipelines can then reference these named tool configurations using the tools directive (e.g., tools { jdk 'JDK 11'; maven 'Maven 3.8' }).
Properly configuring these global settings is essential for Jenkins to interact correctly with your environment, tools, and external services.