How to Set Up Jenkins for Local Development and Testing

To set up Jenkins for local development, clone the jenkinsci/jenkins repository, build the WAR file with Maven using the quick-build profile, and launch the development instance with the Jetty plugin using specific JVM --add-opens flags.

Jenkins is an open-source automation server written in Java and built with Apache Maven. Setting up a local development environment allows you to compile the jenkins.war, run a live instance via the embedded Jetty server, and contribute changes to the core codebase. The official CONTRIBUTING.md and README.md files in the jenkinsci/jenkins repository provide the canonical instructions for preparing your toolchain.

Prerequisites for Jenkins Development

Before building Jenkins locally, you must install a supported JDK (version 21 or 25) and Apache Maven (version 3.9.6 or newer). These requirements are defined in the root pom.xml and enforced by the Maven toolchain. Ensure both java and mvn commands are available on your system PATH before proceeding.

Building the Jenkins WAR File

The first step is to clone the repository and compile the web application archive. The war module contains the pom.xml that assembles jenkins.war, while the root pom.xml orchestrates the multi-module build.

Run the following command to perform a quick build that skips tests:

git clone https://github.com/jenkinsci/jenkins.git
cd jenkins
mvn -am -pl war,bom -Pquick-build clean install

This produces the deployable artifact at war/target/jenkins.war. The -Pquick-build profile accelerates the process by excluding the test suite, which is useful for rapid iteration during development.

Launching a Local Development Instance

Jenkins provides a Maven profile that starts a Jetty server for local testing. Because Jenkins accesses internal JDK modules, you must pass specific --add-opens arguments via MAVEN_OPTS to avoid reflection-related runtime errors.

Start the development server with:

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

The instance will be available at http://localhost:8080/jenkins. This configuration reads the compiled classes from the war module and serves them using the Jetty plugin configuration defined in war/pom.xml.

Developing Frontend Assets with Hot Reload

If you are modifying JavaScript or CSS in the war module, you can enable hot-reload by running the webpack dev server separately. First ensure Yarn is enabled via Corepack, then install the node modules:

corepack enable
yarn install

In one terminal, start Jenkins while skipping the frontend asset 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

In a second terminal, start the frontend watch mode:

yarn start

This setup proxies requests to the Jenkins backend while providing live reloading for changes to the UI assets located in the war module.

Debugging with a Remote JVM Debugger

To attach an IDE debugger, export MAVEN_OPTS with the Java Debug Wire Protocol (JDWP) agent alongside the required --add-opens flags:

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

You can then attach your debugger to localhost:5005. This configuration is essential for stepping through code in the core/src/main/java directory or analyzing the startup behavior of the Jenkins automation server.

Summary

• Prerequisites: Install JDK 21 or 25 and Maven 3.9.6+ as specified in the root pom.xml.
• Build: Use mvn -am -pl war,bom -Pquick-build clean install to generate war/target/jenkins.war.
• Run: Launch with mvn -pl war jetty:run after setting MAVEN_OPTS with the three required --add-opens flags for JDK access.
• Frontend: Use yarn start in the war module for hot-reload, running Jenkins with -Dskip.yarn.
• Debug: Add -agentlib:jdwp to MAVEN_OPTS and attach to port 5005.

Frequently Asked Questions

What JDK versions are supported for local Jenkins development?

According to the CONTRIBUTING.md in the jenkinsci/jenkins repository, you must use JDK 21 or 25 to build and run the current master branch. These versions are enforced by the Maven toolchain plugin defined in the root pom.xml.

Why are the --add-opens JVM arguments required when running Jenkins locally?

Jenkins uses deep reflection to access internal classes within the java.base module (specifically java.lang, java.io, and java.util). Without these --add-opens flags passed via MAVEN_OPTS, the modular JDK throws IllegalAccessException errors during startup, preventing the development instance from initializing.

Can I skip building the frontend assets if I only work on Java code?

Yes. When running mvn -pl war jetty:run, you can append -Dskip.yarn to bypass the Yarn build phases. This accelerates startup if you are only modifying Java source files in the core module and do not need to process JavaScript or CSS changes.

Where is the official documentation for contributing to Jenkins?

The definitive guide is located in the repository's CONTRIBUTING.md file. It covers prerequisite installation, IDE-specific hints, and detailed instructions for building and launching development instances, complementing the high-level overview found in README.md.

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