Spring Boot Build Tools: Maven & Gradle

Spring Boot projects live or die by their build configuration. The build tool sits at the center of everything—pulling in dependencies, running tests, packaging the application, and deploying it. Get the build wrong and nothing else matters. This guide covers Maven and Gradle from the ground up, with Spring Boot–specific plugins, dependency management patterns, and the packaging decisions that determine how your application runs in production.

Introduction to Spring Boot Build Tools

Every Spring Boot project needs a build tool. The two standard options are Maven, with its XML-based pom.xml, and Gradle, with its Groovy or Kotlin DSL build scripts. Both integrate with Spring Boot through dedicated plugins that handle dependency management, auto-configuration, packaging, and running the application.

Spring Boot’s build plugins do the heavy lifting. The spring-boot-maven-plugin and spring-boot-gradle-plugin produce an executable fat JAR that bundles your application code alongside all its dependencies. This is what makes java -jar deployment practical—no application server installation required on the target machine.

The choice between Maven and Gradle rarely comes down to capability. Both can build production-ready Spring Boot applications. The real difference is ergonomics: Maven uses XML and enforces a rigid project structure, while Gradle offers a DSL that scales from simple scripts to complex multi-project builds. Pick the tool your team knows best, then lean into its conventions.

Maven Configuration

2.1 The pom.xml Structure

A Spring Boot Maven project centers on the pom.xml file. The critical piece is the spring-boot-starter dependency hierarchy and the spring-boot-maven-plugin.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.1</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>my-spring-boot-app</artifactId>
    <version>1.0.0</version>
    <name>My Spring Boot Application</name>

    <properties>
        <java.version>21</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!-- Test dependencies -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

The spring-boot-starter-parent is the key to the whole dependency management system. It locks dependency versions, sets default plugin configurations, and inherits plugin management from Spring Boot’s BOM (Bill of Materials). You never specify version numbers for Spring Boot starters when using the parent—version management flows down from the parent POM.

2.2 Spring Boot Maven Plugin

The spring-boot-maven-plugin is what transforms a standard JAR into an executable fat JAR. Without it, your application would require all dependencies on the classpath at runtime. With it, the plugin repackages your artifact to include every dependency under BOOT-INF/lib/.

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <excludes>
            <exclude>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The repackage goal runs automatically during the package phase. It takes the JAR produced by Maven and replaces it with the fat JAR. The build-info goal generates build metadata (application version, Java version, build timestamp) that Spring Boot Actuator exposes automatically at /actuator/info.

2.3 Multi-Module Maven Projects

For larger applications, split the build into multiple modules. A common structure separates domain code from the web layer.

my-project/
├── pom.xml                    ← Parent POM
├── module-domain/
│   └── pom.xml
├── module-web/
│   └── pom.xml
└── module-archive/
    └── pom.xml

<!-- Parent pom.xml -->
<project>
    <groupId>com.example</groupId>
    <artifactId>my-project</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>module-domain</module>
        <module>module-web</module>
        <module>module-archive</module>
    </modules>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.1</version>
    </parent>
</project>

Gradle Configuration

3.1 The build.gradle Structure

Gradle uses a DSL that is more expressive than Maven’s XML. The equivalent Spring Boot Gradle build looks like this:

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.1'
    id 'io.spring.dependency-management' version '1.1.7'
}

group = 'com.example'
version = '1.0.0'

java {
    sourceCompatibility = JavaVersion.VERSION_21
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'

    runtimeOnly 'org.postgresql:postgresql'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

The io.spring.dependency-management plugin is what activates Spring Boot’s dependency management in Gradle. Without it, you would need to specify version numbers for every dependency. With it, the Spring Boot plugin manages versions the same way Maven’s starter-parent does.

3.2 Spring Boot Gradle Plugin

The Spring Boot Gradle plugin handles repackaging, but its configuration looks different from Maven’s XML approach.

bootJar {
    archiveFileName = "${project.name}-${project.version}.jar"
}

bootRun {
    sourceResources sourceSets.main
}

tasks.register('bootJarInfo', BootInfoTask) {
    enabled = true
}

The plugin automatically applies repackage during the build lifecycle. Run ./gradlew bootJar to produce the executable fat JAR, or ./gradlew bootBuildImage to build a container image using Cloud Native Buildpacks.

3.3 Kotlin DSL

If your team prefers Kotlin syntax, use build.gradle.kts:

import org.springframework.boot.gradle.tasks.bundling.BootJar

plugins {
    java
    id("org.springframework.boot") version "3.4.1"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.example"
version = "1.0.0"

java {
    sourceCompatibility = JavaVersion.VERSION_21
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    runtimeOnly("org.postgresql:postgresql")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

tasks.named<BootJar>("bootJar") {
    archiveFileName.set("${project.name}-${project.version}.jar")
}

Dependency Management Best Practices

4.1 Starters are Your Friend

Spring Boot starters are curated dependency sets that follow the convention spring-boot-starter-*. The spring-boot-starter alone pulls in auto-configuration, the Spring context, and logging. Add spring-boot-starter-web and you get MVC, REST, and embedded Tomcat. Add spring-boot-starter-data-jpa and you get Hibernate, transaction management, and Spring Data abstractions.

Never manually assemble the dependencies that a starter provides. Using spring-boot-starter-web rather than listing spring-web, spring-webmvc, tomcat-embed-core, and jackson-databind separately means Spring Boot manages the versions—and more importantly, those versions are tested together as a coherent set.

4.2 Avoiding the Dependency Hell

When multiple libraries pull in conflicting transitive dependencies, use Maven’s dependency tree or Gradle’s dependency insight to trace the conflict.

# Maven: see where a transitive dependency comes from
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core

# Gradle: see why a dependency is included
./gradlew dependencies --configuration runtimeClasspath
./gradlew dependencyInsight --dependency jackson-databind

In Gradle, exclude transitive dependencies explicitly:

implementation('some:library') {
    exclude group: 'org.springframework', module: 'spring-core'
}

In Maven, use an exclusion:

<dependency>
    <groupId>some</groupId>
    <artifactId>library</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

4.3 Managing Dependency and Plugin Versions

One version mismatch rule: never hardcode a version that Spring Boot’s parent already manages. If you want to override a managed version, do it explicitly:

<!-- In Maven, property precedence lets you override -->
<properties>
    <spring-core.version>6.1.2</spring-core.version>
</properties>

// In Gradle, use the dependency management plugin
dependencyManagement {
    resolutionStrategy {
        force 'org.springframework:spring-core:6.1.2'
    }
}

Packaging: JAR vs WAR

5.1 Executable JAR (Default)

Spring Boot’s default packaging is an executable JAR. The fat JAR contains everything needed to run the application with java -jar. No external application server required.

mvn clean package
java -jar target/my-app-1.0.0.jar

./gradlew build
java -jar build/libs/my-app-1.0.0.jar

This approach works for microservices, containerized applications, and any scenario where you control the runtime environment. The container community has converged on this model—Docker images based on eclipse-temurin or amazoncorretto images run Spring Boot fat JARs directly.

5.2 Traditional WAR Deployment

Some environments still require WAR deployment to an external servlet container. Switch packaging to war and mark the embedded server as provided:

<packaging>war</packaging>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

In Gradle:

apply plugin: 'war'

dependencies {
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}

Spring Boot’s main class must then extend SpringBootServletInitializer:

public class Application extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(Application.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Common Build Tasks

6.1 Running Tests

# Maven
mvn test
mvn verify                    # Runs tests + integration tests

# Gradle
./gradlew test
./gradlew verify

6.2 Building Without Tests

mvn package -DskipTests
./gradlew build -x test

6.3 Running the Application

# Maven
mvn spring-boot:run
mvn spring-boot:run -Dspring-boot.run.arguments='--server.port=9000'

# Gradle
./gradlew bootRun
./gradlew bootRun --args='--server.port=9000'

6.4 Building Docker Images

# Maven with Jib
mvn com.google.cloud.tools:jib-maven-plugin:build

# Gradle with Jib
./gradlew jibDockerBuild

Spring Boot’s built-in container building:

# Maven
mvn spring-boot:build-image

# Gradle
./gradlew bootBuildImage

Common Pitfalls

Mixing dependency scopes incorrectly. Runtime dependencies should use runtime (Maven) or runtimeOnly (Gradle) — they are not on the compilation classpath. A dependency in the wrong scope produces a NoClassDefFoundError at runtime even though everything compiled without issue.

Overriding managed versions without understanding compatibility. Spring Boot’s dependency management is a tested set. Bumping spring-core to a newer minor version than the parent specifies can break things that depend on internal APIs. Only override versions when you have a specific reason and have tested the combination.

Forgetting the Spring Boot Maven plugin configuration. Without the plugin, mvn package produces a thin JAR that cannot be run with java -jar. If you need traditional WAR deployment, switch the packaging type or explicitly skip the repackage goal.

Skipping the dependency management plugin in Gradle. Without io.spring.dependency-management, you lose Spring Boot’s version management entirely. Every transitive dependency needs an explicit version, and you inherit full responsibility for version conflicts across the entire dependency tree.

When to Use / When NOT to Use

When to Use Maven

Maven is the right choice when your team has prior experience with it and your project follows conventional conventions. It shines in environments where dependency resolution through Maven Central is the primary concern, because Maven’s dependency metadata model and repository infrastructure are battle-tested and widely understood. Multi-module enterprise builds also favor Maven’s strict project structure and lifecycle enforcement—modules declare their relationships explicitly, and the reactor can order builds correctly without additional configuration.

Use Maven when your organization already has established Maven infrastructure: internal Maven repositories, company-wide parent POMs, or CI pipelines built around Maven goals. Most build problems you run into will have documented solutions because the Maven plugin ecosystem is well-established.

When to Use Gradle

Gradle makes sense on complex builds where Maven’s XML becomes a liability. If you need fine-grained control over task execution order, incremental compilation, or custom build logic that runs across many modules, Gradle’s programming model handles that naturally. The Kotlin DSL gives you type-safe build scripts with IDE support that catches errors before you run the build.

Gradle’s incremental build model cuts build times significantly on large projects because it tracks inputs and outputs at the task level and skips work already done. Build caching and parallel execution are easier to configure in Gradle than in Maven’s lifecycle model.

When NOT to Use Maven

Do not reach for Maven when you need to express build logic that does not map cleanly onto the standard lifecycle phases. If your build requires significant scripting around conditional logic, dynamic artifact generation, or complex orchestration that fights Maven’s conventions, you will spend more time working around the tool than using it.

When NOT to Use Gradle

Avoid Gradle when your team has no experience with it and the project is simple—a straightforward JAR or WAR with a handful of dependencies. The flexibility that makes Gradle powerful also makes it easier to create unmaintainable build scripts. Kotlin DSL has a learning curve, and Gradle’s behavior can differ between versions in ways that are harder to debug than Maven’s more predictable lifecycle.

Trade-Off Table

Dimension	Maven	Gradle
Build Speed	Standard execution; incremental builds limited	Incremental by default; build cache reduces rebuilds significantly
DSL Flexibility	XML-based; strictly structured	Groovy or Kotlin DSL; full programming language expressiveness
Plugin Ecosystem	Large and mature; most tools have Maven plugins	Growing rapidly; some tools lag Maven equivalents
Learning Curve	Shallow for basics; XML conventions are predictable	steeper—DSL syntax, task model, and convention-over-configuration interactions
CI/CD Integration	Excellent; wide tool support and documented patterns	Excellent; native support in most modern CI platforms
Multi-Module Builds	Strong reactor with explicit module ordering	Strong; fine-grained task dependency control
Configuration Complexity	Low for standard projects; grows with custom needs	Lower for custom needs; higher for standard projects due to flexibility
IDE Support	Universal; excellent support across all major IDEs	Very good; Kotlin DSL IDE support improving rapidly
Dependency Management	BOM and dependency plugin; transitive management by exclusion	BOM via plugin; better resolution strategy control
Build Reproducibility	Excellent when lifecycle is followed	Excellent with proper task configuration

Observability Checklist

Build pipeline observability catches problems before they reach production. If you do not monitor your CI/CD pipeline the same way you monitor your running services, you will miss slow builds, flaky tests, and dependency regressions until they hit users.

Build Duration Metrics

• Track build duration per module and alert on regression. A sudden spike in module build time often indicates a dependency being resolved from scratch or a plugin misbehaving.
• Record mvn test and ./gradlew test times over time. Set thresholds that trigger investigation when test suite duration increases beyond 20% from baseline.

Dependency Version Drift Detection

• Run mvn dependency:tree or ./gradlew dependencies in CI and diff outputs against a baseline. Unexpected transitive dependency additions or version changes should block merges.
• Use tools like Dependabot or Renovate to automate dependency update pull requests and track update history.

Plugin Failure Alerting

• Every CI run should produce a structured log that marks pass/fail at the plugin level, not just the goal or task level. Maven’s –fail-at-end can mask partial failures in multi-module builds.
• Alert on repeated plugin download failures—a corrupted or unavailable artifact cache causes intermittent build failures that are hard to diagnose.

Artifact Integrity Checksums

• Generate and verify SHA-256 checksums for every published artifact. Store checksums alongside artifacts in your repository or artifact registry.
• For internal artifacts, verify checksums before promoting to a staging environment.

Maven/Gradle Daemon Memory Usage

• Gradle daemon memory usage should be monitored in CI. Configure org.gradle.jvmargs to set heap limits and prevent daemon OOM kills that produce cryptic build failures.
• Maven daemon (if using Maven daemonizers) similarly needs memory limits.

Security and Compliance Notes

Build security does not get attention until something breaks. The time to integrate security scanning, artifact signing, and license checks into your build pipeline is before you have a problem.

Dependency Vulnerability Scanning

Run OWASP Dependency-Check as part of your build. It cross-references your dependency tree against the National Vulnerability Database (NVD):

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <configuration>
        <failBuildOnCVSS>7</failBuildOnCVSS>
    </configuration>
</plugin>

tasks.register('dependencyCheck', DependencyCheckTask) {
    failBuildOnCVSS = 7
    suppressionFile = file('dependency-check-suppressions.xml')
}

Signing Build Artifacts

Sign artifacts destined for release repositories using GPG for Maven or the Gradle signing plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-gpg-plugin</artifactId>
    <configuration>
        <passphrase>${env.GPG_PASSPHRASE}</passphrase>
    </configuration>
</plugin>

signing {
    useGpgCmd()
    sign configurations.archives
}

Managing Credentials

Never hardcode credentials in pom.xml, build.gradle, or any build script. Use environment variables or CI secrets:

<plugin>
    <configuration>
        <password>${env.MAVEN_REPO_PASSWORD}</password>
    </configuration>
</plugin>

publishing {
    repositories {
        maven {
            url = uri("https://repo.example.com/releases")
            credentials {
                username = System.getenv("MAVEN_REPO_USER")
                password = System.getenv("MAVEN_REPO_PASSWORD")
            }
        }
    }
}

License Compliance Checking

Add the license-maven-plugin or the Gradle equivalent to verify that all dependencies have compatible licenses before release:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>license-maven-plugin</artifactId>
    <configuration>
        <failOnUnknownLicenses>true</failOnUnknownLicenses>
    </configuration>
</plugin>

Private Maven Repository Access Control

If using private repositories (GitHub Packages, Artifactory, Nexus), enforce access control through CI environment variables rather than sharing credentials in configuration files. Rotate credentials regularly and revoke immediately after team member departure.

Real-world Failure Scenarios

Build failures in Spring Boot projects rarely come from application code—they come from the build. These are the scenarios that surface most often in production CI/CD pipelines and how to recover from them.

Build Succeeds, Application Crashes on Startup with NoClassDefFoundError

This is the most common build-classpath mismatch. The application compiled cleanly, all tests passed, but the running application cannot find a class. The culprit is usually a runtime-scoped dependency that was accidentally moved to compile scope. In Maven, check for a missing <scope>runtime</scope> on database drivers or connection pool libraries. In Gradle, verify that runtime-only dependencies use runtimeOnly and not implementation. The fix is to move the dependency to the correct scope—compile-scoped runtime dependencies vanish from the classpath when the fat JAR repackages.

Fat JAR Runs Locally but Fails in Kubernetes with ClassNotFoundException or NoSuchMethodError

This typically means your local environment and the container image are resolving different versions of a transitive dependency. A library on your local Maven/Gradle cache may not match what gets bundled from the build. Run mvn dependency:tree or ./gradlew dependencies inside the container build context and diff against your local output. Look for version conflicts where two libraries pull in different major versions of the same transitive dependency. The solution is to explicitly exclude one version and force a consistent version up the chain.

Gradle Build Cache Returns Stale Classes After Dependency Update

Incremental compilation can cache stale bytecode when a dependency API changes but not the source signatures your code depends on. The build reports success but the running application throws NoSuchMethodError because it is running old compiled classes that do not match the new dependency. Run ./gradlew clean build to invalidate the incremental cache. If it recurs, disable the build cache for that specific task with outputs.cacheIf { false } while you investigate which task is producing incorrect cache keys.

Maven Multi-Module Build Orders Modules Incorrectly

Maven’s reactor determines build order from the dependency graph, but if module A depends on module B’s compiled artifact rather than its source, the reactor may schedule them in the wrong order when you run targets in parallel. The symptom is intermittent ClassNotFoundException in early modules. Fix this by using <skip>true</skip> on the plugin that produces the cross-module artifact or by restructuring the dependency to be source-based rather than artifact-based.

Spring Boot Plugin Skips Repackage and Produces Thin JAR in CI

This happens when the build runs as a different user than the one who originally ran mvn package, or when the CI environment uses a shared cache that partially corrupted the plugin state. The plugin detects that the JAR was already repackaged and skips the step on subsequent runs. Run mvn clean package to force a full rebuild. If it persists, delete the CI cache entirely and rebuild from scratch.

Build Fails with Could Not Resolve Dependencies After Network Partition to Maven Central

Cached resolution failures persist in the local repository metadata. Once Maven marks a dependency as unreachable, it does not retry until the cache expires. Delete the bad resolution from .m2/repository or run mvn -U to force updates. In Gradle, delete the corrupted entry from .gradle/caches/modules-2/files-2.1/ and rebuild.

Quick Recap Checklist

• Using spring-boot-starter-parent for dependency management in Maven
• spring-boot-maven-plugin or Spring Boot Gradle plugin configured for fat JAR
• All Spring Boot dependencies use managed versions (no hardcoded versions for starters)
• Test dependencies scoped correctly (test scope in Maven, testImplementation in Gradle)
• Production database driver on runtime scope (not compile)
• Application starts and runs healthily with java -jar target/*.jar
• Multi-module project uses proper <relativePath/> for parent POM
• Docker image builds successfully from the packaged JAR

Interview Questions

Further Reading

• Maven Documentation: POM Reference — Official POM element reference
• Gradle Build Tool Documentation — Gradle user guide and DSL reference
• Spring Boot Build Plugins — Spring Boot Maven plugin reference
• Spring Boot Gradle Plugin — Spring Boot Gradle plugin reference
• Maven Central Repository — Search for dependencies and verify coordinates
• Dependency Management Plugin for Gradle — Spring dependency management in Gradle

Conclusion

Maven and Gradle are both mature, production-ready build tools for Spring Boot projects. Maven’s XML-based approach and strict conventions make it predictable and widely understood, while Gradle’s DSL provides greater flexibility for complex builds. The spring-boot-starter-parent in Maven and the io.spring.dependency-management plugin in Gradle both provide version management that eliminates the need to specify versions for Spring Boot starters.

Choose Maven for teams with existing Maven expertise and enterprise infrastructure. Choose Gradle for complex builds where incremental compilation, build caching, and fine-grained task control provide meaningful time savings. In both cases, use the Spring Boot plugins to produce executable fat JARs, and never hardcode dependency versions that Spring Boot already manages.