Opscraft
Build tools & artifact repositories · Lesson 2 of 9 · 6 min read

Maven in depth

Coordinates and the POM

Every Maven artifact is identified by GAV — groupId:artifactId:version (plus packaging and optional classifier):

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.acme.orders</groupId>
  <artifactId>orders-service</artifactId>
  <version>1.4.0-SNAPSHOT</version>
  <packaging>jar</packaging>

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

  <properties>
    <java.version>21</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Lifecycle, phases and goals

Maven has three built-in lifecycles: clean, default (build) and site. Running a phase runs all earlier phases of that lifecycle:

Enlarge diagramvalidatecompiletestpackageverifyinstalldeploy~/.m2/repositorythis machine onlyNexusshared repositorymvn package = validate → compile → test → package
Figure 1. Maven's default lifecycle. Running a phase runs every phase before it; install copies to your laptop's ~/.m2, deploy uploads to the shared repository.
Swipe sideways to see all of it, or tap to open it full screen.
Phase What happens
validate Project is correct
compile Compile main sources
test Run unit tests (Surefire)
package Create jar/war
verify Integration tests and checks (Failsafe, coverage gates)
install Copy the artifact into the local repository ~/.m2/repository
deploy Upload the artifact to a remote repository (Nexus/Artifactory)

Plugins bind goals to phases (maven-compiler-plugin:compile to compile). You can run a goal directly: mvn dependency:tree.

Useful CI flags:

mvn -B -ntp verify                # batch mode, no transfer progress noise
mvn -T 1C package                 # parallel build, 1 thread per core
mvn -pl orders-api -am package    # build one module plus the modules it depends on
mvn -o package                    # offline (use local repo only)
mvn -DskipTests package           # compile tests but don't run them
mvn -Dmaven.test.skip=true        # don't even compile tests
mvn -U verify                     # force update of SNAPSHOT dependencies

Dependency scopes

Scope Compile classpath Test Runtime / packaged Example
compile (default) ✓ ✓ ✓ Spring
provided ✓ ✓ ✗ (container provides it) Servlet API in a WAR
runtime ✗ ✓ ✓ JDBC driver
test ✗ ✓ ✗ JUnit
import Only in dependencyManagement for BOMs spring-boot-dependencies

Transitive dependencies and conflicts

Maven resolves conflicts with nearest wins (shortest path in the tree; first declaration on ties). That can silently select an older version than a library needs, causing NoSuchMethodError at runtime.

Enlarge diagramorders-apilib-ajackson-databind 2.12depth 2: nearest, so it winslib-blib-cjackson-databind 2.17depth 3: ignoredFix: pin the version in dependencyManagement or a BOM, and enforce convergence.
Figure 2. Maven picks the version nearest the top of the tree, even if it is older. Here jackson 2.12 wins, and the library that needs 2.17 fails at runtime.
Swipe sideways to see all of it, or tap to open it full screen.

Tools:

mvn dependency:tree -Dincludes=com.fasterxml.jackson.core
mvn dependency:analyze            # used-undeclared / declared-unused

Fixes: pin versions in <dependencyManagement> or import a BOM; add <exclusions>; enforce with the maven-enforcer-plugin (dependencyConvergence, requireUpperBoundDeps, banned dependencies).

Multi-module builds

A parent POM with <modules> builds modules in dependency order (the reactor). dependencyManagement and pluginManagement in the parent centralise versions; children declare dependencies without versions.

Enlarge diagramparent pom.xmlmodules + versionscommonbuilt 1storders-domainbuilt 2ndorders-apibuilt 3rd
Figure 3. A multi-module build. The parent POM manages versions; the reactor builds modules in dependency order.
Swipe sideways to see all of it, or tap to open it full screen.

SNAPSHOT vs release

  • 1.4.0-SNAPSHOT — a moving development version; each deploy gets a timestamped unique version in the repository (1.4.0-20261027.101500-3), and consumers resolve the latest. Snapshot repositories allow redeploy.
  • 1.4.0 — a release; immutable, release repositories forbid redeploy.
  • Never depend on SNAPSHOTs in a release; the maven-release-plugin or CI-driven versioning (mvn versions:set -DnewVersion=1.4.0) replaces them. Many teams now skip SNAPSHOTs and version every CI build (1.4.0-<build>-<sha>), which suits continuous delivery.
Enlarge diagram1.4.0-SNAPSHOT1.4.0Each deploy gets a timestamped copyConsumers get the latest oneFine during developmentNever in a releaseUploaded onceRedeploy is refusedSame bytes foreverWhat you ship
Figure 4. SNAPSHOT versions move; release versions never change.
Swipe sideways to see all of it, or tap to open it full screen.

settings.xml and mirrors

Enlarge diagrammvn / gradlemirrorOf: *Nexus group repomaven-publichostedyour releasesproxycaches Maven Central
Figure 5. With a mirror in settings.xml, every download goes through your repository manager, never straight to the internet.
Swipe sideways to see all of it, or tap to open it full screen.

~/.m2/settings.xml (or a CI-provided file via -s) holds credentials and mirrors so all resolution goes through your repository manager:

<settings>
  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>https://nexus.acme.dev/repository/maven-public/</url>
    </mirror>
  </mirrors>
  <servers>
    <server>
      <id>nexus</id>
      <username>${env.NEXUS_USER}</username>
      <password>${env.NEXUS_TOKEN}</password>
    </server>
  </servers>
</settings>

distributionManagement in the POM says where mvn deploy uploads releases and snapshots; the <id> must match a <server> for credentials.