Tutoriel sur la publication d'artefacts sur Maven Central

Antoine Rey

Cet article présente les étapes qui permettent de publier un projet Open source sur le Central Repository, également connu sous le nom de Maven Central.

Pour réagir au contenu de cet article, un espace de dialogue vous est proposé sur le forum Commentez .

- Titre : Tutoriel sur la publication d'artefacts sur Maven Central

- Auteur : Antoine Rey

- Parution : 18 décembre 2014

- Licence : Copyright ® 2014 Antoine Rey. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Les limites d'un repository personnel

- III. Demander l'accès au service OSSRH

- IV. Préparer sa signature PGP

- V. Configuration Maven

- VI. Publication dans Maven Central

- VII. Résultat

- VIII. Conclusion

- IX. Références

- X. Remerciements

I - Introduction

Lorsque vous rendez Open source un projet, même le plus modeste soit-il, quoi de plus naturel que de vouloir faciliter son utilisation par la communauté de développeurs intéressés ? Dans le monde Java, le dépôt de binaires Open source le plus connu est le Central Repository, également connu sous le nom de Maven Central. En effet, lors de la construction d'un projet Java, Apache Maven essaie par défaut de localiser ses dépendances depuis Maven Central. D'autres outils de build comme Gradle et Ant/Ivy y font également référence. Géré par Sonatype et reposant sur Nexus, Maven Central est accessible en écriture par les développeurs Open source en faisant la demande. Ayant récemment publié des artefacts sur ce repo, ce billet présente les différentes étapes qui m'ont permis d'y arriver.

II - Les limites d'un repository personnel

Il y a deux ans, j'expliquais comment monter sa propre usine de développement Java dans le Cloud à l'aide de GitHub et de Cloudbees. Pour Repository Maven, j'utilisais le Webdav mis gracieusement à disposition par Cloudbees. L'inconvénient principal de cet hébergement est que les artefacts publiés sur ce repository ne sont pas nativement accessibles par Maven. Il est en effet nécessaire de configurer la balise distributionManagement du pom.xml nécessitant ces artefacts. En entreprise, lorsque les builds Maven passent systématiquement par un proxy Maven, cela se complique pour le développeur. Plusieurs choix s'offrent à lui :

1. Référencer le repository Cloudbees dans le proxy Maven de son entreprise ;

2. Déployer les artefacts Maven dans le repository Maven de son entreprise ;

3. Copier/coller le code qui l'intéresse ;

4. Renoncer à l'utilisation du code convoité.

Sans débat, la disponibilité d'artefacts dans le repository Maven Central facilite leur adoption. C'est un critère qui m'avait d'ailleurs convaincu d'adopter DbSetup.

Autre argument et pas des moindres : contrairement à un repository personnel, la pérennité du repository Maven Central est garantie.

III - Demander l'accès au service OSSRH

Le manuel utilisateur de Maven explique les différentes solutions permettant de déployer un artefact dans Maven Central.
Le moyen le plus simple est de passer par l'intermédiaire du service Open source Software Repository Hosting (OSSRH) offert par Sonatype. Ce service offre un espace de staging dans lequel des artefacts « releasés » peuvent être publiés avant d'être promus, puis synchronisés vers Maven Central.

Le guide du service OSSRH explique quelles sont les démarches nécessaires à l'obtention des habilitations permettant de publier un artefact dans le repository Nexus OSSRH.
L'accès au Jira de Sonatype est un prérequis. Il suffit de renseigner un formulaire d'inscription. Les logins/mots de passe de ce Jira serviront à se connecter sur le Nexus de Sonatype et à déployer les artefacts dans OSSRH.

L'accès au Jira permet également d'ouvrir un ticket Jira de demande de création d'un projet. L'information principale à communiquer concerne le groupId Maven des artefacts que vous souhaitez déployer. La demande est examinée par un employé de Sonatype. Pour des raisons de sécurité et de confiance, le groupId est vérifié.

Dans la demande OSSRH-11327, le groupId com.javaetmoi m'a été accordé. Cela me permet de publier des artefacts avec des « sous » groupId comme com.javaetmoi.core.
Moins de 24h après, Joel Orlina avait traité ma demande.

IV - Préparer sa signature PGP

Un prérequis nécessaire à la publication d'un artefact dans Maven Central consiste à signer son artefact à l'aide du standard OpenPGP.
L'installation de GnuPG, la génération de clés privées/publiques et la diffusion de la clé publique sont décrites sur la page Working with PGP signatures.
Les instructions sont claires et une installation sous Windows 7 ne m'a posé aucune difficulté.

Dans le settings.xml local à l'utilisateur, pensez à indiquer le chemin complet du binaire gpg2.exe :

settings.xml

<profiles>
<profile>
<id>ossrh</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<gpg.executable>C:/Software/Dev/GnuPG/gpg2.exe</gpg.executable>
<gpg.passphrase>xxxxxx</gpg.passphrase>
</properties>
</profile
</profiles>

V - Configuration Maven

La dernière étape avant de pouvoir déployer les artefacts de son projet dans Maven Central consiste à configurer le POM de votre projet (le POM parent pour un projet multimodules). La page Apache Maven du Central Repository explique pas à pas quels sont les plugins Maven à configurer et les coordonnées du repository à déclarer.
Pour exemple, je vous invite à vous référer au pom.xml du projet spring-batch-toolkit.

Ne pas oublier de déclarer le server ossrh dans le settings.xml local de l'utilisateur.

VI - Publication dans Maven Central

Déployer une version release de son projet dans Maven Central peut se faire de plusieurs manières :

1. L'utilisation du Maven Release Plugin ;

2. La commande deploy de Maven ;

3. Une publication manuelle à l'aide du plugin Maven nexus-staging.

La page Apache Maven du Central Repository explique les commandes Maven à exécuter.

Pour ma part, j'ai souhaité publier dans Maven Central des artefacts que j'avais déjà « releasés » sur mon repo personnel Cloudbees.
J'ai créé une branche à partir du tag créé lors de la « release maven ». J'ai ensuite reconfiguré le pom.xml comme expliqué ci-dessus. La commande Maven suivante a fait le reste : mvn clean deploy -P. release

Voici un exemple de sortie console que vous obtiendrez en cas de succès :

....
Uploading: https://oss.sonatype.org:443/service/local/staging/deployByRepositoryId/comjavaetmoi-1004/com/javaetmoi/core/javaetmoi-hibernate4-hydrate/2.0/javaetoi-hibernate4-hydrate-2.0-sources.jar.asc
Uploaded: https://oss.sonatype.org:443/service/local/staging/deployByRepositoryId/comjavaetmoi-1004/com/javaetmoi/core/javaetmoi-hibernate4-hydrate/2.0/javaetmi-hibernate4-hydrate-2.0-sources.jar.asc (499 B at 0.1 KB/sec)
[INFO]  * Upload of locally staged artifacts finished.
[INFO]  * Closing staging repository with ID "comjavaetmoi-1004".
Waiting for operation to complete.......
[INFO] Remote staged 1 repositories, finished with success.
[INFO] Remote staging repositories are being released...
Waiting for operation to complete........
[INFO] Remote staging repositories released.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1:47.675s
[INFO] Finished at: Thu Sep 04 20:41:33 CEST 2014
[INFO] Final Memory: 15M/247M
[INFO] ------------------------------------------------------------------------

Avant publication dans Maven Central, le nexus-staging-maven-plugin effectue des vérifications. Ainsi, ma première publication a été rejetée, car aucun développeur n'était mentionné dans le pom.xml. Le nom de la licence Open source choisie pour le projet est également indispensable.

Lors de futures releases, j'utiliserais directement le Maven Release Plugin comme je le faisais jusque-là sur CloudBees.

VII - Résultat

À l'issue de la publication, vous recevrez successivement deux mails :

1. Nexus : « Staging Completed » ;

2. Nexus : « Promotion Completed ».

Voici un extrait du second mail :

Nexus : Promotion Completed email

Message from: https://oss.sonatype.org

Description:
com.javaetmoi.core:javaetmoi-hibernate-hydrate:1.0

Deployer properties:
•    "userAgent" = "Nexus-Client/2.7.2-01"
•    "userId" = xxxx
•    "ip" = xxxx
Details:

The following artifacts have been promoted to the "Releases" [id=releases] repository

/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0.jar
(SHA1: cd0d87951fc2c5ac5c8bef1ca10cd5c40a5a3e3c)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0-javadoc.jar
(SHA1: d43dc47450d0acbed4ce21a2e8ff69de06f03fd3)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0.pom.asc
(SHA1: cbfdc56ff91926164dacd6954782a2b1ade8eef2)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0.pom
(SHA1: 7336a648dc1deb3f6b223eb121ac2a1c0ef6053b)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0-javadoc.jar.asc
(SHA1: a91a7f1f2e5603346c43325c7d009008a9d0de18)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0-sources.jar.asc
(SHA1: 7e014101817772f1b90e5835b2b6b4e45713dcf6)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0-sources.jar
(SHA1: 45dbc2f47bcd690a00604f9c38be54383a99cc46)
/com/javaetmoi/core/javaetmoi-hibernate-hydrate/1.0/javaetmoi-hibernate-hydrate-1.0.jar.asc
(SHA1: 267be3c43664fa096fd38b77df205c4477c51ad0)
Action performed by Antoine Rey (mon email)

Dès réception de ce mail, l'artefact peut alors être téléchargé dans votre repo local Maven.
Pour se faire, ajoutez la dépendance dans le pom.xml :

Dépendance javaetmoi-hibernate4-hydrate

<dependency>
<groupId>com.javaetmoi.core</groupId>
<artifactId>javaetmoi-hibernate4-hydrate</artifactId>
<version>2.0</version>
</dependency>

puis lancez un build : mvn clean install.

Les artefacts sont directement téléchargés depuis Maven Central :

Downloading: http://repo.maven.apache.org/maven2/com/javaetmoi/core/javaetmoi-hibernate4-hydrate/2.0/javaetmoi-hibernate4-hydrate-2.0.pom
Downloaded: http://repo.maven.apache.org/maven2/com/javaetmoi/core/javaetmoi-hibernate4-hydrate/2.0/javaetmoi-hibernate4-hydrate-2.0.pom (12 KB at 9.3 KB/sec)
Downloading: http://repo.maven.apache.org/maven2/com/javaetmoi/core/javaetmoi-hibernate4-hydrate/2.0/javaetmoi-hibernate4-hydrate-2.0.jar
Downloaded: http://repo.maven.apache.org/maven2/com/javaetmoi/core/javaetmoi-hibernate4-hydrate/2.0/javaetmoi-hibernate4-hydrate-2.0.jar (11 KB at 25.0 KB/sec)

VIII - Conclusion

La publication d'un JAR dans Maven Central n'est pas si compliquée. Elle n'est pas non plus réservée aux projets les plus connus. Votre groupId doit être choisi rigoureusement. Si vous disposez d'un nom de domaine, utilisez-le.

Pour automatiser encore davantage la publication de mes « releases » dans Maven Central, il me reste une dernière étape : le faire depuis mon instance Jenkins sur Dev@Cloud. Les plugins Jenkins M2 Release et Promoted Builds devraient m'y aider. Le plus compliqué sera sans doute d'installer et de faire perdurer une clé PGP privée.

IX - Références

- OSSRH Guide

- Repository Nexus OSSRH de Sonatype

- Jira de Sonatype

- Page Apache Maven du Central Repository

- PGP signatures

- Apache Maven GPG plugin

- Guide pour uploader des artefacts dans le Maven Central Repository

X - Remerciements

Cet article a été publié avec l'aimable autorisation d'Antoine Rey.

Nous tenons à remercier Malick SECK pour sa relecture orthographique attentive de cet article et Régis Pouiller pour la mise au gabarit.