Maven — `settings.xml` & GitLab Package Registry (`com.dynors`)¶

Guide opérationnel pour résoudre les dépendances com.dynors:* avec Maven (projet mono-module ou multi-module), en s’appuyant sur le GitLab Package Registry (projets dynors-core et dynors-extensions).

Source canonique du template

Le fichier exemple officiel est versionné dans le workspace local multi-repos dynors/ (pas un monorepo Git unique) :
config/maven-settings.xml.example
Même contenu décrit ici : à copier ou fusionner dans votre ~/.m2/settings.xml. Si vous n’avez pas ce dossier, récupérez le fichier auprès de l’équipe plateforme ou via la branche / synchronisation interne habituelle.

Pour la vue d’ensemble (Gradle, dépannage 401, politique versions) : CONFIGURATION_ACCES_DEPENDANCES.md (racine du workspace dynors, section 5 « Option C : Maven ») et docs/TRACECONFIG_REGISTRY_MAVEN_GRADLE_2026-04.md dans ce même workspace.

1. Prérequis¶

Élément	Détail
Maven	3.8.1+ pour que `${env.VAR}` soit résolu dans `settings.xml` (sinon il faut injecter le token en clair — déconseillé).
Token GitLab	PAT avec `read_api` + `read_registry` (voir Obtenir un token).
Accès groupe / projet	Rôle au moins Reporter sur les projets qui publient les packages utilisés.

2. Mise en place concrète (poste développeur)¶

Étape A — Récupérer le modèle¶

Depuis la racine du dossier workspace où se trouvent config/, core/, etc. :

# Option 1 : remplacer tout le settings utilisateur (OK si vous n’avez pas d’autres serveurs Maven dedans)
cp config/maven-settings.xml.example ~/.m2/settings.xml

# Option 2 : settings existant — ouvrir les deux fichiers et fusionner à la main :
# - les blocs <server> (auth HTTP)
# - le <profile id="dynors-gitlab-registry"> (repositories + pluginRepositories)
# - <activeProfile>dynors-gitlab-registry</activeProfile>

Étape B — Authentifier sans mettre le PAT dans le fichier¶

Le template utilise ${env.GITLAB_TOKEN} dans les en-têtes HTTP (header Private-Token), ce qui convient à un Personal Access Token.

export GITLAB_TOKEN="glpat-…"   # votre PAT ; ne pas commiter cette ligne
mvn -q dependency:resolve

Tester sur votre projet :

cd /chemin/vers/votre-projet-maven
export GITLAB_TOKEN="glpat-…"
mvn dependency:resolve

Si les artefacts com.dynors:* se téléchargent, la configuration est bonne.

Étape C — Aligner les `<id>` Maven avec le `pom.xml`¶

Les identifiants gitlab-dynors-core et gitlab-dynors-extensions doivent être strictement identiques entre :

les <server><id>…</id> du settings.xml ;
les <repository><id>…</id> (et idem pluginRepository) du POM (ou du pom parent).

Exemple minimal de déclaration dans un pom.xml (à adapter au BOM / versions réelles — voir Versions et dépendances) :

<repositories>
  <repository>
    <id>gitlab-dynors-core</id>
    <url>https://gitlab.com/api/v4/projects/75907047/packages/maven</url>
  </repository>
  <repository>
    <id>gitlab-dynors-extensions</id>
    <url>https://gitlab.com/api/v4/projects/76017499/packages/maven</url>
  </repository>
</repositories>

Projets core + extensions : les deux blocs sont en général nécessaires (comme pour Gradle — config/dynors-repositories.gradle.kts).

3. Obtenir un token GitLab¶

GitLab → Preferences → Access Tokens.
Scopes minimum pour consommer les packages : read_api, read_registry.
Pour publier des artefacts sur un projet : ajouter write_registry sur ce projet (cas pipeline release — hors scope de ce guide).

Ne jamais commiter le PAT dans un settings.xml versionné, un pom.xml, ni une doc (utiliser des placeholders documentés ; côté lint secrets, voir Gitleaks — usage, précautions & dépannage).

4. CI GitLab (lecture des packages `com.dynors`)¶

En pipeline, CI_JOB_TOKEN est injecté automatiquement par GitLab ; l’en-tête attendu n’est pas le même que pour un PAT :

Contexte	Variable / jeton	En-tête HTTP dans `settings.xml`
Poste dev	`GITLAB_TOKEN` (PAT)	`Private-Token`
Job GitLab	`CI_JOB_TOKEN`	`Job-Token`

Cible sécurité : réduire les PAT longue durée dans les variables de projet ; préférer CI_JOB_TOKEN quand les permissions du job token permettent la lecture des packages dynors-core / dynors-extensions (projets du groupe dynors). Sinon, PAT technique à durée limitée, stocké comme variable masquée et idéalement synchronisé depuis Vault (voir Vault, secrets CI & feuille de route).

4.1 Variante A — `CI_JOB_TOKEN` + `settings.xml` généré (sans secret dans Git)¶

Maven 3.8.1+ résout ${env.CI_JOB_TOKEN} dans le fichier généré. Le heredoc utilise des quotes sur le délimiteur (<<'SETTINGS') pour que le shell ne remplace pas la variable avant l’écriture du fichier — c’est Maven qui lit ${env.CI_JOB_TOKEN} au moment du build.

Fragment versionné (recommandé) : dépôt dynors/dynors-core, fichier
config/gitlab-ci-maven-dynors-registry.yml — modèles .dynors-maven-registry-job-job-token (CI_JOB_TOKEN + en-tête Job-Token), .dynors-maven-registry-job-private-token (GITLAB_TOKEN + Private-Token), et .dynors-maven-registry-cache (cache .m2/repository, optionnel).

Dans votre .gitlab-ci.yml :

include:
  - project: "dynors/dynors-core"
    ref: main
    file: config/gitlab-ci-maven-dynors-registry.yml

build-maven-app:
  extends:
    - .dynors-maven-registry-job-job-token
    - .dynors-maven-registry-cache
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS -DskipTests=false verify

Variante PAT : remplacer par extends: .dynors-maven-registry-job-private-token et définir la variable CI GITLAB_TOKEN (masquée).

Sans include (environnement restreint) : recopier le before_script / heredoc depuis ce fichier — évite la dérive en dupliquant le XML à la main.

Accès inter-projets (Package Registry)

Si le pipeline tourne dans un projet satellite (dynors-projects/...), vérifier dans GitLab que le job token du projet peut télécharger les packages des projets 75907047 et 76017499 (réglages CI/CD → Job token / listes d’accès inbound selon la version GitLab). Sinon le build renverra 401 malgré un CI_JOB_TOKEN présent.

4.2 Variante B — variable masquée `GITLAB_TOKEN` (PAT)¶

Créer un PAT technique (scopes read_api, read_registry) ou récupérer un secret synchronisé depuis Vault (processus équipe — voir page Vault).
Dans GitLab : Settings → CI/CD → Variables → GITLAB_TOKEN (masked, protected si branches protégées uniquement).
Utiliser extends: .dynors-maven-registry-job-private-token du fragment dynors-core/config/gitlab-ci-maven-dynors-registry.yml (génère Private-Token + ${env.GITLAB_TOKEN}).

Ne jamais commiter un settings avec valeur en clair.

5. Règ DYNORS sur les versions `com.dynors.*`¶

En CI / prod : pas de dépendances com.dynors:* en -SNAPSHOT tirées du registry (train de releases stables — voir règle workspace dynors-core-stable-versions).
Le profil exemple désactive snapshots sur les URL GitLab listées : aligné avec cette politique ; un profil Maven séparé « chantier » peut les réactiver exceptionnellement.

6. Dépannage¶

Symptôme	Piste
401 Unauthorized	Token absent ou mauvais header (`Private-Token` vs `Job-Token`) ; PAT expiré ; pas les scopes `read_registry` ; `<id>` repository ≠ `<id>` server.
Could not find artifact com.dynors:…	Registry manquant dans le POM ; ou seul core est déclaré alors que le module vient d’extensions.
`${env.GITLAB_TOKEN}` non substitué	Maven antérieur à 3.8.1, ou variable non exportée dans le shell / job CI.
Conflit avec un autre `settings.xml`	Utiliser `mvn -s /chemin/vers/settings-dynors.xml` pour forcer un fichier dédié au build DYNORS.

Script de diagnostic côté API (sans Maven) : à la racine workspace dynors, ./scripts/check-gitlab-access.sh avec GITLAB_TOKEN ou CI_JOB_TOKEN exporté.

7. Récap checklist¶

[ ] ~/.m2/settings.xml contient servers + profile + activeProfile (ou équivalent fusionné).
[ ] GITLAB_TOKEN exporté ou CI correctement injecté (Job-Token / variable masquée).
[ ] pom.xml déclare les même <id> et les URLs registry core 75907047 et extensions 76017499 si besoin.
[ ] mvn dependency:resolve OK sur un module qui dépend de com.dynors.
[ ] Aucun secret dans Git ; PAT révoqué en cas de fuite.

8. Équivalent Gradle¶

Même registres et logique d’en-têtes : config/dynors-repositories.gradle.kts dans le workspace dynors. Les projets Spring Boot internes DYNORS utilisent en pratique Gradle + Kotlin ; Maven reste supporté pour outils, générateurs ou apps legacy.

9. Secrets & Vault (cible DYNORS)¶

Les PAT et jetons de build ne doivent pas vivre « en dur » dans le dépôt. Stratégie coffre, rotation et feuille de route (chantiers Transit, HA, CI, etc.) : Vault, secrets CI & feuille de route.

Maven — settings.xml & GitLab Package Registry (com.dynors)¶