Maven and Gradle Builds skill for Codex

Done well means: the build runs from a clean checkout with only the wrapper (./mvnw or ./gradlew) and a JDK, versions are declared in one place (BOM, parent POM or version catalog), every conflict resolution is explicit and explained, and the build is reproducible on CI with the same JDK toolchain.

Inspect first

ls mvnw gradlew pom.xml build.gradle* settings.gradle* gradle/libs.versions.toml 2>/dev/null
./gradlew --version            # Gradle and the JVM running it
./mvnw -v
cat gradle/wrapper/gradle-wrapper.properties .mvn/wrapper/maven-wrapper.properties 2>/dev/null

Read AGENTS.md for the canonical build and test command. Always use the wrapper, never a globally installed mvn or gradle, so the version matches CI. First runs download the distribution and dependencies (network); with network off, try --offline (Gradle) or -o (Maven) against the local cache before asking for approval.

Which tool’s rules apply

Situation	Choice
Existing project	Keep its tool. Migrating Maven to Gradle (or back) is a project, not a fix
New Kotlin or Android project	Gradle with Kotlin DSL and a version catalog
New plain Java service, team values convention over flexibility	Maven 3.9.x with the wrapper
Groovy build.gradle to Kotlin DSL	Convert module by module; see references/gradle-kotlin-dsl.md

Java version: toolchains, not the host JDK

// build.gradle.kts
java {
    toolchain { languageVersion = JavaLanguageVersion.of(21) }
}

<!-- pom.xml -->
<properties>
  <maven.compiler.release>21</maven.compiler.release>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

Gradle toolchains can auto-provision a JDK (needs network and the foojay resolver plugin in settings). Maven compiles with the JDK running Maven unless you configure toolchains; release guarantees the API level but CI must still run a JDK at least that new.

Dependency versions in one place

Gradle version catalog (gradle/libs.versions.toml):

[versions]
spring-boot = "3.5.6"
junit = "5.13.4"

[libraries]
spring-boot-bom = { module = "org.springframework.boot:spring-boot-dependencies", version.ref = "spring-boot" }
junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter" }
jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind" }

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

dependencies {
    implementation(platform(libs.spring.boot.bom))   // versions come from the BOM
    implementation(libs.jackson.databind)
    testImplementation(platform(libs.junit.bom))
    testImplementation(libs.junit.jupiter)
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Maven: import BOMs in dependencyManagement and omit versions in dependencies:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>${spring-boot.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Version numbers above are examples; check the latest stable release before writing them.

Resolving conflicts

Tool	Resolution rule	Inspect
Maven	Nearest definition wins (shortest path), then first declared	./mvnw dependency:tree -Dverbose -Dincludes=com.fasterxml.jackson.core
Gradle	Highest requested version wins (plus constraints, platforms, rich versions)	./gradlew :app:dependencyInsight --dependency jackson-databind --configuration runtimeClasspath

Symptoms of a conflict: NoSuchMethodError, ClassNotFoundException, NoClassDefFoundError, IncompatibleClassChangeError at runtime while compilation passed.

Fix in this order:

1. Align with a BOM/platform for the library family (Jackson, Netty, gRPC, AWS SDK).
2. Upgrade the direct dependency that drags the old version.
3. Maven: declare the version in dependencyManagement. Gradle: a constraints {} block with a because("...") reason.
4. Exclusions only for genuinely unwanted artifacts (duplicate logging bindings), with a comment saying why.

Guard against regressions: Maven Enforcer dependencyConvergence or requireUpperBoundDeps; Gradle failOnVersionConflict() only for small graphs (it is noisy).

Multi-module structure

• Maven: parent POM with <modules>, shared pluginManagement and dependencyManagement. Build one module plus what it needs: ./mvnw -pl app -am verify.
• Gradle: settings.gradle.kts with include(":app", ":core"); shared configuration in convention plugins under an included build build-logic/, never in allprojects {} / subprojects {} blocks (they break configuration cache and isolated projects).
• Gradle java-library: api for types exposed in the module’s public signatures, implementation for everything else. Overusing api slows recompilation and leaks dependencies.

Build speed

# gradle.properties
org.gradle.caching=true
org.gradle.configuration-cache=true
org.gradle.parallel=true
org.gradle.jvmargs=-Xmx3g -XX:+UseParallelGC

• Configuration cache is the preferred mode in Gradle 9; plugins that are incompatible are reported by the first run. Fix or upgrade them rather than disabling the cache.
• Find slow tasks with ./gradlew build --profile (local HTML report). Build scans (--scan) upload data to a third party and need the user’s agreement.
• Maven: ./mvnw -T 1C verify for parallel modules; skip nothing in CI that protects correctness (-DskipTests only locally).

Reproducibility and supply chain

• Commit the wrapper files (gradlew, gradle/wrapper/*, mvnw, .mvn/wrapper/*). Update with ./gradlew wrapper --gradle-version <x.y> (run twice: once to update the properties, once to regenerate scripts with the new version) or ./mvnw wrapper:wrapper -Dmaven=<x.y.z>.
• Gradle dependency locking: dependencyLocking { lockAllConfigurations() } then ./gradlew dependencies --write-locks.
• Gradle dependency verification: ./gradlew --write-verification-metadata sha256 help writes gradle/verification-metadata.xml; review it, do not regenerate it blindly after a checksum failure.
• Avoid dynamic versions (1.+, latest.release, Maven version ranges) in applications.

Gotchas

• Gradle implementation(platform(...)) aligns versions; enforcedPlatform overrides even higher transitive versions and leaks to consumers of libraries. Use it only in applications.
• Maven <scope>provided</scope> dependencies are absent at runtime outside a container; Spring Boot fat jars need them as compile scope.
• Kotlin DSL tasks.test { useJUnitPlatform() } is required for JUnit 5; without it Gradle runs zero tests and reports success.
• Gradle 9 requires Java 17+ to run Gradle itself; compile for older targets via toolchains.
• A plugin version in both the catalog and pluginManagement causes confusing resolution; declare it once.
• mvn install to share modules locally hides reactor problems; build from the root with -pl ... -am instead.

Verification

./gradlew clean build --warning-mode all     # deprecations surface before the next major
./gradlew :app:dependencies --configuration runtimeClasspath > deps-after.txt
./mvnw -q clean verify
./mvnw dependency:tree -Dverbose > deps-after.txt

Diff dependency trees before and after any version change and list every resolved version that moved. Confirm the test count did not drop to zero.

Report template

**Build:** Gradle 9.x wrapper, Kotlin DSL, toolchain Java 21, configuration cache on
**Problem:** NoSuchMethodError in JsonMapper: jackson-databind 2.15 forced by legacy-sdk
**Fix:** imported jackson-bom 2.19.x as platform; removed manual exclusion
**Resolved changes:** jackson-* 2.15.4 -> 2.19.2 (6 artifacts); nothing else moved
**Checks:** ./gradlew build green, 1,284 tests run (unchanged)