Maven Packaging, install, deploy, Distribution Management, Signing, and Repository Publishing: Concepts, Architecture, and Mental Model

1. The practical problem: a successful compile does not define a release

Previous chapters made the model, dependency graph, plugin executions, tests, and governance explicit. Publishing adds another boundary: a consumer outside the current reactor needs a stable coordinate and bytes in a repository. A build can compile successfully yet still publish the wrong version, wrong bytes, incomplete metadata, or artifacts signed with an exposed key.

The central question is therefore not “did Maven succeed?” but “which bytes became authoritative for which coordinate, in which repository, under which identity and credential boundary?”

2. The artifact state machine

flowchart TD
  S[Source commit + pom.xml] --> P[package]
  P --> T[target/ main JAR]
  T --> V[verify]
  V --> A[attached sources / javadoc / signatures]
  A --> I[install]
  I --> L[isolated local repository coordinate]
  L --> D[deploy]
  D --> R[release or snapshot repository]
  R --> C[clean consumer]

The arrows are lifecycle progression, not permission to promote automatically. package creates the main project artifact. This chapter binds source and Javadoc attachment at verify. install copies the project POM and artifacts into the selected local Maven repository. deploy runs after install and writes the publication to the configured deployment repository.

3. Name each state store before touching it

4. Coordinates and attached artifacts

The main artifact is addressed by groupId:artifactId:version plus packaging/type. An attached artifact shares those core coordinates but adds a classifier such as sources or javadoc. It is still part of one project publication, not an unrelated dependency.

target/
  hello-publisher-1.0.0.jar
  hello-publisher-1.0.0-sources.jar
  hello-publisher-1.0.0-javadoc.jar

5. package, install, and deploy are not synonyms

6. distributionManagement, IDs, and credentials

<distributionManagement> describes where a project is published. Its repository <id> is an identity key. When authentication is needed, Maven uses that ID to select the matching <server> entry from settings. The POM can therefore be portable while credentials stay outside version control.

<distributionManagement>
  <repository>
    <id>lab-auth-repo</id>
    <url>http://127.0.0.1:8765/repository/releases</url>
  </repository>
</distributionManagement>

7. Releases and snapshots carry different repository semantics

A final version such as 1.0.0 should be treated as immutable in a production repository. A version ending in -SNAPSHOT is intentionally mutable as development advances. Maven deployment metadata can map a base snapshot coordinate to timestamp/build-number instances, so the repository can distinguish successive snapshot publications while consumers still request the snapshot version.

A local file: repository is useful for observing layout and metadata, but it does not enforce the immutability policy a production repository manager should enforce. The lab will exploit that limitation safely to demonstrate why repository policy matters.

8. Checksum, signature, provenance: complementary evidence

A checksum answers “are these bytes the same as the expected bytes?” A digital signature answers “did a holder of the corresponding private key sign these bytes?” Neither statement by itself proves that the source commit was reviewed, that tests passed, or that the artifact came from the intended CI run. Provenance and release records connect those additional facts.

The Maven GPG Plugin signs project artifacts and POMs with GnuPG, but the private key is an external security asset. This course never commits or exports a real private signing key. The hands-on path uses a disposable synthetic detached signature to teach verification mechanics, then shows GPG as the production integration boundary.

9. Read-only inspection before publication

set -euo pipefail
./mvnw -v
java -version
./mvnw help:effective-pom -Dverbose > effective-pom.xml
./mvnw help:evaluate -Dexpression=project.groupId -q -DforceStdout
./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout
./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout
grep -nE "distributionManagement|lab-releases|lab-snapshots" effective-pom.xml

This is read-only model inspection. It proves the wrapper/JDK identity and the publication coordinates before any repository mutation occurs.

10. DevOps connection: promotion is a controlled trust transition

Reliable delivery separates build from promotion. A production pipeline should build a candidate once, test and record its identity, then promote those same bytes rather than silently rebuilding different bytes for each environment. Maven’s packaging and repository machinery supplies the artifact mechanics; repository immutability, credential policy, provenance, and environment promotion remain governance concerns around that mechanism.

Knowledge check

11. Bridge to the guided workflow

Lesson 2 makes every transition observable: create the project, inspect the JAR, attach sources/Javadocs, compare package/install/deploy side effects, publish to a disposable file repository, generate checksum/signature evidence, and consume the coordinate from a clean repository.

Official references and version notes

Version-sensitive statements were checked against Apache Maven primary documentation on 2026-08-24. The mandatory Maven path pins Maven 3.9.16 via Maven Wrapper 3.3.4, JDK 21 to run Maven, Java 17 as the compiler release target, Compiler Plugin 3.15.0, JAR Plugin 3.5.1, Install Plugin 3.1.4, Deploy Plugin 3.1.4, Source Plugin 3.4.0, Javadoc Plugin 3.12.0, Help Plugin 3.5.2, and GPG Plugin 3.2.8.

Maven 4 remains preview-stage in the current Apache download page, so this chapter does not silently switch publishing semantics to Maven 4.

• Apache Maven 3.9.16 — Download / current release
• Apache Maven Wrapper 3.3.4
• Maven Install Plugin 3.1.4
• Maven Deploy Plugin 3.1.4
• deploy:deploy parameters and alternative repository syntax
• Maven JAR Plugin 3.5.1
• Maven Source Plugin 3.4.0
• Maven Javadoc Plugin 3.12.0
• Maven GPG Plugin 3.2.8
• Maven Settings reference — servers and credential indirection
• Maven repository layout