Guide pratique pour Maven et GitLab Registry

4 janvier 2025

Industrialiser le développement logiciel est une pratique courante dans les entreprises modernes. Il est essentiel de se conformer aux politiques de sécurité de l’entreprise pour garantir la confidentialité et l’intégrité des livrables. GitLab intègre un registre de paquets qui permet de stocker et de gérer les artefacts de vos projets de manière sécurisée. C’est une solution robuste compatible avec les outils de build et de gestion de dépendances les plus populaires, tels que NPM, PyPI, Composer, et bien sûr Maven.

Dans ce guide pratique pour Maven et GitLab Registry, vous apprendrez à sécuriser vos artefacts et à garantir leur disponibilité aux membres de votre équipe. Vous découvrirez comment uploader des JAR privés dans GitLab, les télécharger lors du build Maven, et configurer le déploiement des paquets finaux de votre projet.

Configuration de Maven pour GitLab Registry

GitLab protège les artefacts stockés dans son registre en respectant les règles de sécurité configurées pour le projet. Selon le paramétrage, ces artefacts peuvent être visibles par les membres du projet, les membres du groupe ou les utilisateurs invités.

Pour contrôler l’accès aux artefacts via Maven, nous devons configurer les informations de connexion dans le fichier settings.xml. Ces informations sont nécessaires pour que Maven puisse s’authentifier auprès de GitLab.

Obtenir un token d’accès

Le registre de paquets GitLab accepte les tokens d’accès suivants :

Les Personal Access Tokens : associés à un utilisateur, ils permettent d’accéder à tous les projets auxquels il a accès.
Les Deploy Tokens : associés à un projet, ils permettent d’accéder uniquement aux artefacts de ce projet. Une variante de ce token existe pour les groupes.
Les CI Job Tokens : générés automatiquement pour les jobs CI/CD, ils permettent d’accéder au registre du projet via un pipeline d’intégration continue.

Pour créer votre token, consultez la documentation officielle de GitLab.

Configuration de Maven

Les tokens d’accès sont analysés par GitLab en consultant les headers HTTP. Pour que Maven puisse utiliser ces tokens, nous devons ajouter la configuration suivante dans le fichier settings.xml :

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">

  <!-- ... -->

  <servers>
    <server>
      <id>gitlab-maven</id> <!-- <1> -->
      <configuration>
        <httpHeaders>
          <property>
            <name>Deploy-Token</name> <!-- <2> -->
            <value>private-token</value> <!-- <3> -->
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>

  <!-- ... -->

</settings>

L’identifiant du serveur gitlab-maven est choisi de manière arbitraire, mais il devra être réutilisé pour les paramétrages suivants.

Conformément à la documentation de GitLab, nous utilisons le name approprié. Dans ce cas, c’est un Deploy-Token.

Nous définissons la valeur correspondant au token d’accès que vous avez généré précédemment.

Configuration générique

La configuration précédente est spécifique à un token d’accès. Nous l’utilisons généralement pour notre propre poste de développement. Cependant, si vous souhaitez partager votre projet avec d’autres développeurs, il est recommandé d’éviter de stocker le token dans le fichier settings.xml.

Heureusement, Maven nous permet d’utiliser les variables d’environnement dans ses fichiers de configuration. Ainsi, chaque développeur peut définir son propre token d’accès sans modifier le fichier settings.xml. La commande mvn extrait les valeurs depuis l’environnement du terminal et les utilise pour l’authentification.

Pour cela, nous pouvons modifier le fichier settings.xml comme suit :

 <!-- settings.xml -->
 <!-- ... -->
       <configuration>
         <httpHeaders>
           <property>
-            <name>Deploy-Token</name>
-            <value>private-token</value>
+            <name>${GITLAB_TOKEN_TYPE}</name>
+            <value>${GITLAB_TOKEN}</value>
           </property>
         </httpHeaders>
       </configuration>
 <!-- ... -->

Nous déclarons ici l’utilisation des variables d’environnement GITLAB_TOKEN_TYPE et GITLAB_TOKEN pour le type et la valeur du token d’accès. Si vous le souhaitez, vous pouvez définir des noms de variables différents. L’important est de les déclarer dans votre environnement avant d’exécuter la commande mvn.

Uploader des JAR privés dans GitLab

Lorsque nous maintenons un projet Java privé, il est courant qu’il soit dépendant de librairies tierces distribuées par nos clients ou partenaires. Malheureusement, ces librairies ne sont pas toujours accessibles via un Artifactory. Nous devons donc trouver une solution pour les gérer intelligemment et de manière sécurisée sur notre propre infrastructure.

La solution que je vous propose ici est d’utiliser le registre de paquets GitLab pour stocker ces artefacts. Cela nous permet de les partager avec les membres de notre équipe tout en garantissant leur confidentialité et en restant compatible avec Maven.

La commande suivante nous permet d’uploader un JAR dans le registre de paquets GitLab (pour plus de détails, voir la documentation Maven) :

$ mvn -s settings.xml deploy:deploy-file \
  -Durl=https://${GITLAB_HOST}/api/v4/projects/${GITLAB_PROJECT_ID}/packages/maven \
  -DrepositoryId=gitlab-maven \
  -Dfile=./third-party-lib.jar \
  -DgroupId=com.lavoiedudev.client \
  -DartifactId=third-party-lib \
  -Dversion=1.0.0 \
  -Dpackaging=jar <1>
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- deploy:3.1.1:deploy-file (default-cli) @ standalone-pom ---
[INFO] pom.xml not found in third-party-lib.jar
Uploading to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.jar
Uploaded to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.jar (677 B at 680 B/s)
Uploading to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.pom
Uploaded to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.pom (411 B at 745 B/s)
Downloading from gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/maven-metadata.xml
Uploading to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/maven-metadata.xml
Uploaded to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/maven-metadata.xml (317 B at 599 B/s)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.267 s
[INFO] Finished at: 2024-10-23T09:12:56+02:00
[INFO] ------------------------------------------------------------------------

Comme mentionné précédemment, j’utilise dans cette commande mon fichier settings.xml contenant les informations d’authentification.

Une fois la commande Maven exécutée, le JAR est uploadé dans le registre de paquets GitLab. Vous pouvez vérifier son existence en consultant l’interface web de GitLab (Menu du projet > Paquets & Registre > Registre de paquets).

Téléchargement des JAR depuis GitLab lors du build Maven

Maintenant que notre third-party-lib.jar est stocké dans GitLab, nous allons configurer notre projet pour le télécharger lors du build Maven.

Configuration du pom.xml

Pour cela, nous devons configurer le fichier pom.xml de notre projet afin que Maven puisse accéder au registre de paquets GitLab comme dépôt de dépendances.

 <!-- pom.xml -->
 <!-- ... -->
+  <repositories>
+    <repository>
+      <id>gitlab-maven</id> <1>
+      <url>https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven</url> <2>
+    </repository>
+  </repositories>
 <!-- ... -->

L’identifiant du dépôt doit correspondre à celui défini dans le fichier settings.xml.

Remplacez <private-gitlab-host> et <project-id> par vos propres valeurs.

Téléchargement des dépendances Maven

Notre projet est maintenant configuré pour télécharger les dépendances depuis le registre de paquets GitLab. Utilisez la commande suivante pour lancer la génération :

$ mvn -s settings.xml clean install
...
Downloading from gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.pom
Downloaded from gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.pom (411 B at 226 B/s)
Downloading from gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.jar
Downloaded from gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/client/third-party-lib/1.0.0/third-party-lib-1.0.0.jar (677 B at 37 B/s)
...

Durant le build Maven, les dépendances de notre projet sont téléchargées depuis Maven Central ou le registre de paquets GitLab. Vous pouvez observer les traces du téléchargement dans les logs de Maven.

Déployer les artefacts dans GitLab Registry

Configuration du pom.xml

Pour déployer les artefacts finaux de notre projet dans le registre de paquets GitLab avec la commande mvn deploy, nous devons compléter la configuration du fichier pom.xml pour spécifier où et comment uploader les artefacts.

 <!-- pom.xml -->
 <!-- ... -->
+  <distributionManagement>
+    <repository>
+      <id>gitlab-maven</id>
+      <url>https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven</url>
+    </repository>
+    <snapshotRepository>
+      <id>gitlab-maven</id>
+      <url>https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven</url>
+  </distributionManagement>
 <!-- ... -->

Assurez-vous d’utiliser le bon identifiant de dépôt et de remplacer <private-gitlab-host> et <project-id> par vos propres valeurs.

Déployer les artefacts générés

Une fois la configuration du fichier pom.xml terminée, déployez les artefacts générés par Maven dans le registre de paquets GitLab avec la commande suivante :

$ mvn -s settings.xml deploy
...
[INFO] --- deploy:3.1.1:deploy (default-deploy) @ example ---
Uploading to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/1.0.0/example-1.0.0.pom
Uploaded to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/1.0.0/example-1.0.0.pom (2.5 kB at 840 B/s)
Uploading to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/1.0.0/example-1.0.0.jar
Uploaded to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/1.0.0/example-1.0.0.jar (2.7 kB at 1.3 kB/s)
Downloading from gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/maven-metadata.xml
Uploading to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/maven-metadata.xml
Uploaded to gitlab-maven: https://<private-gitlab-host>/api/v4/projects/<project-id>/packages/maven/com/lavoiedudev/example/maven-metadata.xml (302 B at 258 B/s)
[INFO] ------------------------------------------------------------------------
...

Les artefacts de notre projet sont uploadés dans le registre de paquets GitLab. Vous pouvez vérifier leur présence dans l’interface web de GitLab (Menu du projet > Paquets & Registre > Registre de paquets).

Conclusion

En conclusion, interfacer Maven avec le registre de paquets GitLab est une solution efficace pour gérer et sécuriser les artefacts de vos projets. Ce guide pratique vous a montré comment configurer Maven pour uploader et télécharger des JAR privés, ainsi que pour déployer les artefacts générés par votre projet.

Pour interfacer votre projet Maven avec GitLab Registry, suivez ces étapes :

Configurer le settings.xml Maven pour accéder au registre de paquets GitLab grâce à un token d’accès.
Configurer le pom.xml de votre projet pour télécharger et uploader les artefacts depuis et vers le registre de paquets GitLab.
Utiliser les commandes Maven pour télécharger, générer et déployer vos artefacts en toute sécurité.

En suivant ces étapes, vous pouvez assurer la confidentialité et l’intégrité de vos artefacts tout en facilitant leur partage avec les membres de votre équipe. L’utilisation de GitLab Registry avec Maven permet de centraliser la gestion des dépendances et des artefacts, rendant vos processus de build et de déploiement plus robustes et sécurisés.

Laisser un commentaire Annuler la réponse

Vous devez vous connecter pour publier un commentaire.