Jenkins Module Structure: How the Core, War, CLI, and WebSocket Components Are Organized

Jenkins is organized as a multi-module Maven project where the parent POM orchestrates distinct modules—core, war, cli, websocket, and bom—that separate the runtime engine, packaging, command-line tooling, and dependency management into discrete, version-aligned artifacts.

The jenkinsci/jenkins repository follows a strict modular architecture defined by Apache Maven. Understanding this Jenkins module structure is essential for contributors who need to navigate the codebase, debug build issues, or extend specific functionality without touching unrelated systems.

Overview of the Maven Multi-Module Layout

At the repository root, the pom.xml acts as the parent POM. It declares common properties such as revision, winstone.version, and node.version, manages plugin configurations, and lists the <modules> that compose the complete application.

The project defines the following key modules:

• bom – Generates a Bill-of-Materials POM that centralizes dependency versions for reproducible builds across all transitive dependencies.
• core – Contains the Jenkins runtime, API classes (hudson.*, jenkins.*), Stapler view rendering, and built-in functionality.
• war – Assembles the deployable jenkins.war file, bundling the core, plugins, static assets, and an embedded servlet container.
• cli – Implements the command-line interface for remote interaction over SSH or HTTP.
• websocket/spi – Defines the Service Provider Interface for WebSocket communication used by the UI.
• websocket/jetty12-ee9 – Provides the Jetty EE9-based implementation of the WebSocket SPI.

Core Modules and Their Responsibilities

bom (Bill of Materials)

The bom module generates a dependency management POM that ensures every submodule and plugin uses identical artifact versions. This eliminates version conflicts and simplifies upgrades across the entire project.

core (The Jenkins Runtime)

Located in core/, this module produces jenkins-core.jar, the heart of the application. It contains the server initialization logic, model classes, security realms, and job execution pipelines.

Key entry point in core/src/main/java/hudson/Main.java:

// core/src/main/java/hudson/Main.java
Jenkins jenkins = new Jenkins("my-jenkins", new File("/var/jenkins_home"));
jenkins.setSecurityRealm(SecurityRealm.NO_AUTHENTICATION);
jenkins.setAuthorizationStrategy(AuthorizationStrategy.UNSECURED);

Other modules depend on core as a compile-time dependency. The war module packages this JAR, while the cli module invokes core APIs to communicate with remote instances.

war (Packaging and Distribution)

The war module in war/ uses the maven-war-plugin to aggregate jenkins-core.jar, the CLI JAR, WebSocket implementations, and bundled plugins into a single WEB-INF directory structure. The resulting artifact is the familiar jenkins.war ready for deployment to any servlet container or execution via the embedded Winstone/Jetty server.

The main launcher resides in war/src/main/java/executable/Main.java, which initializes the embedded container on startup.

cli (Command-Line Interface)

The cli module compiles into jenkins-cli.jar, enabling remote administration. It parses arguments in hudson.cli.CLI and connects to running Jenkins instances via SSH or HTTP protocols.

Execute a remote build from the command line:

# cli/src/main/java/hudson/cli/CLI.java

java -jar jenkins-cli.jar -s http://localhost:8080/ build my-job

websocket (SPI and Implementation)

The WebSocket subsystem uses a split architecture to decouple the API from the provider. The websocket/spi module defines WebSocketSession and related interfaces in websocket/spi/src/main/java/jenkins/websocket/WebSocketSession.java. The websocket/jetty12-ee9 module provides the concrete implementation in websocket/jetty12-ee9/src/main/java/jenkins/websocket/Jetty12EE9Provider.java.

This separation allows Jenkins to swap WebSocket providers without modifying core code. Listen to build events programmatically:

// websocket/spi/src/main/java/jenkins/websocket/WebSocketSession.java
WebSocketSession session = WebSocketSession.create(...);
session.addListener(event -> System.out.println("Build event: " + event));

How the Modules Interact at Build Time

The build follows a strict dependency graph orchestrated by the parent POM:

1. Compilation Phase: Maven builds core first, producing the core library.
2. Assembly Phase: The war module pulls core, cli, and the WebSocket implementation into its WEB-INF/lib directory via transitive dependencies.
3. Testing Phase: Integration tests in the test module verify the interaction between core and war artifacts.
4. Reporting Phase: The coverage module aggregates JaCoCo reports across all modules.

The bom module injects version constants into every submodule, ensuring that dependencies like Stapler, Winstone, and Jetty remain consistent throughout the dependency tree.

Key Source Files and Entry Points

File Path	Description
pom.xml	Parent POM declaring modules and global properties.
core/pom.xml	Core module definition building jenkins-core.jar.
core/src/main/java/hudson/Main.java	Server entry point for instantiating Jenkins objects.
war/pom.xml	WAR packaging configuration.
war/src/main/java/executable/Main.java	Launcher for the embedded Jetty/Winstone container.
cli/pom.xml	CLI module building jenkins-cli.jar.
cli/src/main/java/hudson/cli/CLI.java	Command-line argument parsing and remote connection logic.
websocket/spi/src/main/java/jenkins/websocket/WebSocketSession.java	SPI interface for WebSocket sessions.
websocket/jetty12-ee9/src/main/java/jenkins/websocket/Jetty12EE9Provider.java	Jetty EE9 implementation of the WebSocket SPI.

Summary

• Jenkins uses a Maven multi-module structure with a parent POM at the repository root.
• The core module provides the runtime engine and API, consumed by other modules.
• The war module assembles the final deployable artifact including core, CLI, and WebSocket components.
• The cli module enables remote administration via jenkins-cli.jar.
• WebSocket functionality is split between an SPI module and a Jetty EE9 implementation module for clean abstraction.
• The bom module centralizes dependency versions to ensure build consistency.

Frequently Asked Questions

What build tool does Jenkins use for its module structure?

Jenkins uses Apache Maven as its build tool. The repository contains a root pom.xml that defines the multi-module project structure, with each major component (core, war, cli, websocket) residing in its own subdirectory with its own pom.xml.

Which module contains the main Jenkins application logic?

The core module contains the main application logic. It houses the server runtime, model classes (hudson.model.*), security infrastructure, and the Stapler web framework integration. All other modules depend on the artifacts produced by core.

How does the WebSocket module architecture enable provider swapping?

The WebSocket subsystem uses a Service Provider Interface (SPI) pattern. The websocket/spi module defines abstract interfaces like WebSocketSession, while websocket/jetty12-ee9 provides the concrete implementation. This separation allows the Jenkins team to replace Jetty with alternative WebSocket providers by implementing the same SPI contracts without touching core code.

Where is the executable WAR file assembled in the source tree?

The war module assembles the executable WAR file. Located in the war/ directory, its pom.xml configures the maven-war-plugin to bundle jenkins-core.jar, static resources, and the embedded servlet container into jenkins.war, which is output to the target/ directory after compilation.

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