Maven 2 Repositories, Snapshots, Releases, Metadata, Checksums, and Maven Client Configuration: Configuration, Design Choices, and Tradeoffs

1. Release/snapshot separation is an operating control

Sonatype supports Maven repositories with Release, Snapshot, or Mixed version policies. A Mixed repository is valid, but separate hosted repositories create clearer retention, permissions, promotion, cleanup, and incident boundaries. A developer can be allowed to publish snapshots while release publication remains a narrower CI privilege. Operations can retain releases longer than snapshots without encoding every lifecycle distinction into one policy.

2. mirrorOf: control egress at the Maven client

Apache Maven's mirror rules map repository IDs to an alternate URL; Maven does not aggregate multiple matching mirrors. * redirects every repository request to the selected mirror. external:* excludes localhost and file repositories, which can be useful when integration tests intentionally use local fixtures.

The central question is not “which pattern is shortest?” It is “which network paths does the organization intentionally allow?” A bypass around Nexus can defeat routing rules, caching, namespace controls, audit assumptions, and later Repository Firewall/IQ policies.

3. Deployment policy protects artifact identity

Current Nexus hosted repositories expose three deployment policies: Disable redeploy (the default), Allow redeploy, and Read-only. For releases, Disable redeploy is the safer default because a coordinate such as 1.0.0 should continue to identify the same bytes. If a fix is required, publish 1.0.1 rather than rewriting history.

Snapshots have different semantics. Repeated snapshot publication should create/update the metadata needed to locate unique snapshot values. That mutability belongs in the snapshot lane, not the release lane.

4. Checksums and signatures: choose what failure you are trying to detect

Do not “fix” checksum or TLS errors by disabling validation. Determine whether the expected artifact changed, the upstream is wrong, local cache is corrupt, or a network/proxy layer modified the response.

Maven can make checksum handling explicit in a repository definition. In a disposable client profile, checksumPolicy=fail tells Maven to fail when checksum validation fails instead of merely warning. This is a client-side repository policy; it is not PGP signature verification and it does not establish provenance.

<repository>
  <id>academy-public</id>
  <url>http://127.0.0.1:8081/repository/academy-ch06-public/</url>
  <releases>
    <enabled>true</enabled>
    <checksumPolicy>fail</checksumPolicy>
  </releases>
  <snapshots>
    <enabled>true</enabled>
    <checksumPolicy>fail</checksumPolicy>
  </snapshots>
</repository>

When a mirror with mirrorOf=* redirects this repository, the mirror controls the actual remote URL while the repository policy still expresses how Maven treats release/snapshot updates and checksums for that repository definition. Keep these client semantics separate from Nexus blob checksums, package signatures, and Nexus authorization.

5. Internal coordinates and dependency-confusion risk

If com.example.academy is your controlled internal namespace, allowing Maven to fall back directly to public repositories can create ambiguity: a public artifact with the same coordinate may satisfy a request depending on routing and version selection. A Nexus group with internal hosted repositories ordered ahead of public proxies helps express ownership, but client/network governance must also prevent unapproved bypass.

flowchart TD
Q[Maven requests internal GAV] --> M[Mirror routes to Nexus group]
M --> H{Internal hosted match?}
H -->|yes| I[Serve controlled internal artifact]
H -->|no| P{Public proxy allowed for namespace?}
P -->|blocked by routing policy| F[Fail closed and investigate]
P -->|allowed| U[Query approved public upstream]
U --> C[Cache result in proxy]
C --> Q

Routing rules are taught in Chapter 13, but the principle belongs here: the client mirror, group order, repository routing rule, and network egress policy are different controls. Do not assume one replaces all the others.

6. Maven local cache versus Nexus proxy cache

Maven's local repository belongs to one workstation/CI workspace. Nexus's proxy cache belongs to the shared repository service. If a dependency exists in ~/.m2, Maven may not ask Nexus at all. If it is absent locally but cached in Nexus, Maven contacts Nexus while Nexus may not contact Central. If both caches are cold, the request can reach the upstream.

7. Worked decision: 40 developers, protected releases

Requirement: developers consume internal releases, snapshots and Central through one URL; only CI publishes releases; developers may publish snapshots; integration tests occasionally use file repositories; internal namespaces must not resolve from the public Internet.

8. Design exercise: write an ADR before touching Nexus

Create a one-page architecture decision record with: read endpoint, release target, snapshot target, mirror pattern, allowed exceptions, deployment policies, internal namespace prefixes, publisher identities, retention intent, and how you will test a fresh client. Then compare the ADR to the repository configuration from Lesson 2. Any mismatch is either a configuration bug or an undocumented design change.

Knowledge check

9. Summary

Maven repository design is policy expressed through version lanes, mirror scope, namespace routing, deployment immutability, credentials, and cache boundaries. The next lesson deliberately breaks those boundaries and diagnoses the evidence in the correct order.

Official references and version notes

• Nexus Repository Download and 3.95.x release notes — current self-hosted baseline.
• Sonatype: Maven Repositories — Maven version/layout policies, default repositories, grouping, settings and deployment examples.
• Configurable Repository Fields — hosted deployment policy, proxy caching, and group ordering.
• Components API and REST API Reference — supported component/asset inspection and upload boundaries.
• Apache Maven Download — current Maven 3 stable line.
• Apache Maven Settings Reference — localRepository, servers, mirrors, environment interpolation and profiles.
• Using Mirrors for Repositories — mirrorOf matching and single-repository patterns.
• Apache Maven Deploy Plugin — deployment goals and repository-id matching.

Version-sensitive statements were rechecked against Sonatype and Apache Maven primary documentation on 2026-08-26. The mandatory lab pins Nexus Repository Community Edition 3.95.2 and Apache Maven 3.9.16. Nexus 3.95.2 was released 2026-08-21; Maven 3.9.16 is the current recommended Maven 3 release. Nexus 3.87+ requires Java 21 when using an external JVM and official Nexus packages include a bundled Java 21 runtime. Re-check live support/download pages before executing these labs.