How to Set Up a Local Jenkins Development Environment: A Complete Guide

Clone the jenkinsci/jenkins repository, install JDK 21 or 25 with Maven 3.9.6+, build the WAR with mvn -am -pl war,bom -Pquick-build clean install, and launch with mvn -pl war jetty:run using the required --add-opens JVM flags.

Setting up a local Jenkins development environment requires preparing a Java toolchain and leveraging the Maven-based build system defined in the repository root pom.xml. Whether you are patching core functionality in core/src/main/java or tweaking the web UI, the process documented in CONTRIBUTING.md provides a reliable path to a runnable instance.

Prerequisites for Jenkins Development

Before compiling the source, ensure your workstation meets the toolchain requirements specified in CONTRIBUTING.md. Jenkins is a Java application that requires specific JDK and Maven versions to build correctly.

Install the following:

• JDK 21 or 25 – The root pom.xml enforces these versions through the maven-enforcer-plugin. Ensure JAVA_HOME points to a compatible distribution.
• Apache Maven 3.9.6 or newer – Earlier versions may fail to resolve dependencies or handle the multi-module structure correctly.

Verify your installation:

java -version
mvn -version

Building the Jenkins WAR

The build process generates jenkins.war in the war/target/ directory. The root pom.xml organizes the project into modules, including war and bom (Bill of Materials).

To compile without running tests, use the quick-build profile:

# Clone the repository

git clone https://github.com/jenkinsci/jenkins.git
cd jenkins

# Build the WAR and required modules

mvn -am -pl war,bom -Pquick-build clean install

The -am flag ensures upstream modules compile first, while -pl war,bom limits the build to the WAR and BOM artifacts. The resulting war/target/jenkins.war contains the standalone web application.

Launching a Development Instance

You do not need an external servlet container for local testing. The war/pom.xml configures the Jetty Maven Plugin, allowing you to run Jenkins directly from the command line.

Jenkins requires access to internal JDK modules, so you must open specific Java packages using --add-opens flags. Set these via the MAVEN_OPTS environment variable:

MAVEN_OPTS='--add-opens java.base/java.lang=ALL-UNNAMED \
            --add-opens java.base/java.io=ALL-UNNAMED \
            --add-opens java.base/java.util=ALL-UNNAMED' \
mvn -pl war jetty:run

Once the console shows "Jenkins is fully up and running," navigate to http://localhost:8080/jenkins. The instance runs with an empty JENKINS_HOME by default, creating a pristine environment for testing.

Debugging with a Remote JVM

To attach an IDE debugger, modify MAVEN_OPTS to include the Java Debug Wire Protocol (JDWP) arguments:

MAVEN_OPTS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \
            --add-opens java.base/java.lang=ALL-UNNAMED \
            --add-opens java.base/java.io=ALL-UNNAMED \
            --add-opens java.base/java.util=ALL-UNNAMED' \
mvn -pl war jetty:run

Configure your IDE to connect to localhost:5005. You can now set breakpoints in core/src/main/java and step through the Jenkins core logic.

Developing Frontend Assets

The Jenkins UI relies on JavaScript and CSS assets built with Yarn and webpack. If you are modifying frontend code, running a dedicated dev server enables hot-reload functionality.

First, ensure Node.js and Yarn are available. The project recommends using Corepack to manage the Yarn version:

corepack enable
yarn install

Run Jenkins without processing frontend assets, then start the webpack dev server in a separate terminal:

# Terminal 1: Run Jenkins (skip yarn processing)

MAVEN_OPTS='--add-opens java.base/java.lang=ALL-UNNAMED \
            --add-opens java.base/java.io=ALL-UNNAMED \
            --add-opens java.base/java.util=ALL-UNNAMED' \
mvn -pl war jetty:run -Dskip.yarn

# Terminal 2: Start the webpack dev server

yarn start

The yarn start command watches for changes in the war module and pushes updates to the browser automatically. This workflow eliminates the need to restart the Java process for every CSS or JavaScript modification.

Summary

• Prerequisites: Install JDK 21 or 25 and Maven 3.9.6+ as defined in the root pom.xml.
• Build: Use mvn -am -pl war,bom -Pquick-build clean install to generate war/target/jenkins.war.
• Run: Execute mvn -pl war jetty:run with the three --add-opens flags in MAVEN_OPTS to satisfy JDK module access requirements.
• Debug: Add -agentlib:jdwp arguments to MAVEN_OPTS and attach your IDE to port 5005.
• Frontend: Use yarn start alongside mvn jetty:run -Dskip.yarn for hot-reload of UI assets.

Frequently Asked Questions

What JDK versions are officially supported for Jenkins development?

According to the CONTRIBUTING.md documentation and the root pom.xml configuration, Jenkins supports JDK 21 and JDK 25 for development. The build enforces these versions to ensure compatibility with modern Java features while maintaining the --add-opens requirements for internal module access.

Can I run Jenkins development without installing Maven globally?

While the documentation assumes a local Maven installation, you can use the Maven Wrapper if included in the repository. However, the standard instructions in CONTRIBUTING.md reference Maven commands directly, so having Apache Maven 3.9.6 or newer installed globally provides the most straightforward experience when you set up a local Jenkins development environment.

How do I skip the frontend build when I only changed Java code?

Pass the -Dskip.yarn property to the Maven Jetty plugin: mvn -pl war jetty:run -Dskip.yarn. This prevents the build from processing JavaScript assets, significantly speeding up startup times when you are only modifying Java classes in the core module.

Where is the jenkins.war file located after building?

The compiled WAR file is generated at war/target/jenkins.war relative to the repository root. This path is configured in war/pom.xml and represents the deployable artifact containing the Jenkins core, plugins, and web resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}