Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 41 ยท Releasing and Production

Publishing: Install, Deploy and Maven Central

Understand the difference between mvn install and mvn deploy, how to configure distributionManagement, sign artifacts with GPG and publish to Maven Central.

Building a jar on your machine is only half of the job. For other people, or other projects of your own, to use it, the artifact has to land in a repository. Maven has two commands for that, install and deploy, and a whole set of rules about what a repository will accept, especially the public one, Maven Central.

This lesson explains where each command sends files, how distributionManagement and credentials fit together, what Central demands (sources, javadoc, signatures, complete metadata) and how SNAPSHOT versions are treated differently from releases. Publishing needs accounts and servers, so the commands are read-only here; the runnable Java stand-ins check a publishing checklist and decide which repository a version belongs to.

Two phases, two destinations

install Copies the artifact into ~/.m2 on this machine.
deploy Uploads it to a remote repository.

deploy runs install's work first, because it follows verify and install in the lifecycle.

1 / 2

install versus deploy

Both are lifecycle phases (see lifecycles and phases). mvn install runs everything up to and including install, which copies the packaged artifact and its POM into your local repository (~/.m2/repository, see repositories and the local cache). That is how a sibling project on the same computer finds your library without any network. mvn deploy goes one step further: it runs install-level work, then the deploy phase uploads the artifact, POM and checksums to a remote repository.

Terminal
mvn install                 # local only, fast, no credentials
mvn deploy                  # uploads to the repository from distributionManagement
mvn deploy -DskipTests      # not recommended for real releases

Use install while developing a library that another local project consumes. Use deploy only from CI or a release machine. A common team rule is that nobody deploys from a laptop, because a build from CI is repeatable and traceable.

distributionManagement and credentials

Where does deploy upload? The POM names the target in distributionManagement, with one repository for releases and one for snapshots:

XML
<distributionManagement>
  <repository>
    <id>company-releases</id>
    <url>https://repo.example.com/repository/releases/</url>
  </repository>
  <snapshotRepository>
    <id>company-snapshots</id>
    <url>https://repo.example.com/repository/snapshots/</url>
  </snapshotRepository>
</distributionManagement>

Maven picks snapshotRepository when the version ends in -SNAPSHOT, and repository otherwise. The id is only a label, but it is how Maven finds the username and password: a <server> with the same id in settings.xml (see settings, mirrors and credentials). Credentials never go into the POM.

XML
<servers>
  <server>
    <id>company-releases</id>
    <username>${env.REPO_USER}</username>
    <password>${env.REPO_TOKEN}</password>
  </server>
</servers>

Release repositories are normally immutable: uploading 1.4.0 a second time is refused. Snapshot repositories accept many uploads of the same version, and Maven stores each with a timestamp.

SNAPSHOT versus release

A version ending in -SNAPSHOT means "work in progress toward this version". Maven keeps timestamped copies and checks for newer ones (daily by default) when a project depends on a snapshot. Releases are stable promises: once 1.4.0 exists, it must never change. That has consequences:

  • A release must not depend on any SNAPSHOT, or it would not be reproducible. The enforcer plugin has a rule for this.
  • Central accepts releases only. Snapshots go to your own repository, or to Central's snapshot service if you have enabled it.
  • If a bad release goes out, you do not replace it; you publish 1.4.1.

Publishing to Maven Central

Maven Central is the default public repository, and publishing to it goes through the Central Portal. The steps, in order:

  1. Create an account and claim a namespace that matches your groupId. Using a reverse domain you own (com.example) is verified by a DNS record; io.github.yourname is verified through your GitHub account.
  2. Generate a user token in the portal. It is a username/password pair for uploading, stored as a server entry in settings.xml.
  3. Make the POM complete and the artifacts signed (next sections).
  4. Upload a bundle with the Central publishing Maven plugin, which can validate and publish automatically or leave the upload waiting for you to confirm in the portal.
XML
<plugin>
  <groupId>org.sonatype.central</groupId>
  <artifactId>central-publishing-maven-plugin</artifactId>
  <version>0.8.0</version>
  <extensions>true</extensions>
  <configuration>
    <publishingServerId>central</publishingServerId>
  </configuration>
</plugin>

Plugin versions change; check the current one in the Central documentation before copying this. After a successful publication the artifact is visible on Central within minutes to hours and can never be deleted, which is why you validate first.

The required metadata

Central rejects an upload whose POM lacks the fields that tell users what the library is and who stands behind it:

XML
<name>Example Library</name>
<description>Small utilities for parsing durations.</description>
<url>https://github.com/example/example-library</url>
<licenses>
  <license>
    <name>Apache-2.0</name>
    <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
  </license>
</licenses>
<developers>
  <developer>
    <name>Ada Example</name>
    <email>[email protected]</email>
  </developer>
</developers>
<scm>
  <connection>scm:git:https://github.com/example/example-library.git</connection>
  <developerConnection>scm:git:ssh://[email protected]/example/example-library.git</developerConnection>
  <url>https://github.com/example/example-library</url>
</scm>

Sources, javadoc and signatures

Two companion jars are required, produced by plugins bound to the package phase:

XML
<plugin>
  <artifactId>maven-source-plugin</artifactId>
  <executions>
    <execution><goals><goal>jar-no-fork</goal></goals></execution>
  </executions>
</plugin>
<plugin>
  <artifactId>maven-javadoc-plugin</artifactId>
  <executions>
    <execution><goals><goal>jar</goal></goals></execution>
  </executions>
</plugin>

Then every file is signed with a GPG key, producing .asc signatures next to each artifact. Users can verify that the file really came from you:

Terminal
gpg --gen-key
gpg --keyserver keyserver.ubuntu.com --send-keys <KEY_ID>
mvn deploy -Prelease

The maven-gpg-plugin runs in the verify phase and reads the key passphrase from an environment variable or settings.xml, never from the POM. Put signing, sources, javadoc and publishing in a release profile, so ordinary builds stay quick and need no key. Together with checksums (.sha1, .md5 and newer algorithms), signatures are the basis of the trust model described in dependency security.

A repository router

The first stand-in decides which repository URL a version belongs to, and what path the files get. The path rule is the standard layout: the groupId with dots as folders, then artifactId, then version.

Java Where does this version go?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

A real deployment also writes checksum files and maven-metadata.xml, and snapshots get a timestamped file name; the model shows only the shape.

A pre-publish checklist verifier

The second stand-in plays the role of Central's validation. It reads a simplified POM description and a list of produced files, and reports every problem at once, the way a good build rule should. The real checks happen on the server after upload, which is why running them locally is worth the effort.

Java Checklist verifier

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Fix each reported problem in the code (add a developer, drop the snapshot dependency, add the missing files) and the list shrinks to zero. That loop is exactly how you prepare a first release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does mvn install put the artifact?

    install copies the artifact and POM into the local repository so other projects on the machine can use them. Only deploy uploads to a remote repository.
  2. 2. Which repository does deploy use for a project whose version is 2.0.0-SNAPSHOT?

    Maven chooses snapshotRepository for versions ending in -SNAPSHOT and repository for releases.
  3. 3. Which of these must be present for a Central release?

    Central requires signatures (.asc files), sources and javadoc jars and complete POM metadata. Private keys never belong in a POM.
  4. 4. Where should the repository password live?

    Credentials belong in settings.xml (ideally read from environment variables), linked to the repository through the shared id.

Summary

  • install copies to your local repository; deploy uploads to a remote one, usually from CI.
  • distributionManagement names the release and snapshot repositories; the id links them to server credentials in settings.xml.
  • Releases are immutable and must not depend on snapshots.
  • Central needs a verified namespace, complete POM metadata, sources and javadoc jars, and GPG signatures, typically in a release profile.
  • A checklist verifier in your build catches problems before an irreversible upload.

Next, automate the version changes around a release in Release Workflows and Reproducible Builds.