How to Set Up Jenkins from the jenkinsci/jenkins Repository: Complete Developer Guide

To set up Jenkins from the jenkinsci/jenkins repository, install JDK 21+ and Maven 3.9.6+, clone the source, run mvn -am -pl war,bom -Pquick-build clean install to compile the WAR, and launch it with java -jar war/target/jenkins.war or via Maven Jetty for hot-reloading.

The jenkinsci/jenkins repository hosts the complete source code for Jenkins core, including the REST API, plugin system, and web interface. Whether you are contributing patches, testing core changes, or running a development instance, building from source gives you full control over the build process and enables rapid iteration via hot-reload workflows.

Prerequisites for Building from Source

Before you set up Jenkins from the jenkinsci/jenkins repository, ensure your environment meets the following requirements listed in CONTRIBUTING.md:

• Java Development Kit (JDK) 21 or later – Required to compile the Java source
• Apache Maven 3.9.6+ – Drives the build via the root pom.xml
• Node.js and Yarn (optional) – Only needed if modifying frontend assets; enable via corepack enable

The project uses a multi-module Maven structure where the root pom.xml defines the jenkins-parent (lines 29‑32) and enforces Java compatibility through the maven-enforcer-plugin.

Clone the Repository

Retrieve the latest source code from the master branch:

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

This creates a local copy of the core modules (core, war, cli, bom) and configuration files needed to build the executable WAR.

Build the Jenkins WAR

The war module packages Jenkins into an executable .war file containing the embedded Winstone servlet container. For rapid development, use the quick-build profile to skip tests:

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

This command (documented in CONTRIBUTING.md lines 31‑35) compiles Java sources, bundles frontend assets, and produces war/target/jenkins.war in approximately 30 seconds. The -am flag ensures all dependencies in the reactor are built first, while -pl war,bom limits the build to the WAR and Bill of Materials modules.

Run Jenkins Locally

You have two primary methods to start a development instance after building.

Option 1: Run the Generated WAR

Execute the packaged WAR directly to start Jenkins on the default port:

java -jar war/target/jenkins.war

The instance becomes available at http://localhost:8080. This method uses the Winstone container bundled in war/pom.xml (dependencies section, lines 68‑108) and is the fastest way to verify a production-like build.

Option 2: Launch via Maven Jetty (Hot-Reload)

For active development, use the Jetty Maven plugin to enable hot-reloading of Java classes without restarting the server:

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

This configuration (see CONTRIBUTING.md lines 45‑49) opens required Java modules for the embedded container and allows immediate propagation of compiled changes to the running instance.

Frontend Development Setup

If you are modifying the modern UI assets (React/JavaScript), run the Yarn dev server alongside the backend for hot-reload of frontend code:

# Terminal 1: Backend (skip Maven's UI build)

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: Frontend dev server

export PATH=$PWD/node:$PWD/node/node_modules/corepack/shims:$PATH
yarn start

Enable Corepack first with corepack enable to make Yarn available. This workflow (detailed in CONTRIBUTING.md lines 72‑84) runs Webpack in dev mode while the Jetty backend serves the API.

Code Quality and Testing

Before submitting changes, ensure your code meets the project's standards:

• Auto-format Java: mvn spotless:apply
• Lint UI code: yarn lint or yarn lint:fix

The repository enforces Checkstyle, ESLint, Prettier, and Spotless (see CONTRIBUTING.md lines 86‑94).

To run tests, choose from three Maven profiles:

• Light tests: mvn -Plight-test test (fast unit tests)
• Smoke tests: mvn -Psmoke-test test
• Full suite: mvn verify (comprehensive, may take 30+ minutes)

Summary

• Install JDK 21+, Maven 3.9.6+, and optionally Node/Yarn for UI work
• Clone the repository from https://github.com/jenkinsci/jenkins.git
• Build the WAR using mvn -am -pl war,bom -Pquick-build clean install
• Run via java -jar war/target/jenkins.war for standalone mode or mvn -pl war jetty:run for development with hot-reload
• Use Yarn (yarn start) in parallel for frontend development (-Dskip.yarn on the backend)
• Format code with Spotless and verify with the appropriate Maven test profile

Frequently Asked Questions

What Java version is required to build Jenkins?

Jenkins core requires JDK 21 or later to compile and run. The root pom.xml enforces this via the maven-enforcer-plugin to ensure compatibility with modern language features and security standards.

How do I enable hot-reloading for Java code changes?

Use the Maven Jetty plugin instead of running the WAR directly. Execute mvn -pl war jetty:run with the appropriate MAVEN_OPTS to open Java modules. This allows you to recompile classes and see changes immediately without restarting the server.

Can I build Jenkins without running tests?

Yes. Append the -Pquick-build Maven profile to your build command: mvn -am -pl war,bom -Pquick-build clean install. This skips the test suite and produces the WAR in roughly 30 seconds, ideal for rapid iteration.

Where is the executable WAR file located after building?

The WAR file is generated at war/target/jenkins.war relative to the repository root. This artifact contains the core runtime, embedded Winstone servlet container, and bundled plugins, ready for deployment or local execution.

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