Intégration GitLab CI/CD✯

Cette page explique comment utiliser le registre registry.isima.fr depuis vos pipelines GitLab :

Pousser une image construite par le pipeline
Récupérer une image du registre dans un job
Utiliser une image du registre comme image du job
Utiliser une image du registre comme service (base de données, etc.)

Projet d'exemple « clé en main »

Pour démarrer rapidement, inspirez-vous du dépôt boilerplate maintenu par le CRI : cri-public/gitlab-ci-registry-boilerplate. Il fournit un .gitlab-ci.yml prêt à l'emploi qui construit une image et la pousse sur registry.isima.fr. Forkez-le ou copiez-en le pipeline, puis adaptez le nom du projet Harbor et celui de votre image.

Configurer l'intégration Harbor✯

L'accès au registre depuis GitLab se fait via l'intégration native Harbor. Une fois configurée, GitLab injecte automatiquement les identifiants du registre dans tous les pipelines du projet, sans avoir à créer de variables à la main.

Pré-requis : un compte robot

N'utilisez jamais votre CLI secret personnel. Créez d'abord un compte robot dédié au projet, avec les permissions strictement nécessaires (Pull pour récupérer, Pull + Push pour publier).

Dans votre projet GitLab, ouvrez Settings > Integrations
Sélectionnez Harbor
Cochez Active et renseignez :
- Harbor URL : https://registry.isima.fr
- Harbor project name : le nom de votre projet Harbor (ex. mon-projet)
- Username : l'identifiant d'un compte robot (ex. robot$mon-projet+gitlab-ci)
- Password : le secret du compte robot
Cliquez sur Test settings and save changes

Configuration de l'intégration Harbor dans GitLab

L'intégration expose alors automatiquement les variables CI/CD suivantes à vos jobs :

Variable	Contenu
`$HARBOR_URL`	URL complète du registre (`https://registry.isima.fr`)
`$HARBOR_HOST`	Nom d'hôte du registre (`registry.isima.fr`)
`$HARBOR_PROJECT`	Nom du projet Harbor configuré
`$HARBOR_USERNAME`	Identifiant (le compte robot)
`$HARBOR_PASSWORD`	Secret associé
`$HARBOR_OCI`	URL OCI (`oci://registry.isima.fr`), utile pour les charts Helm

Configuration au niveau d'un groupe

L'intégration peut être définie une seule fois au niveau d'un groupe GitLab pour être héritée par tous ses projets. Une configuration au niveau projet a priorité sur celle du groupe.

Utilisez un compte robot, pas votre compte personnel

Les identifiants saisis dans l'intégration sont accessibles à tous les pipelines du projet. Renseignez-y un compte robot aux permissions limitées, et veillez à ce qu'un .gitlab-ci.yml malveillant ne puisse pas exfiltrer $HARBOR_PASSWORD (variable non protected visible dans les branches non protégées).

Permissions du robot pour l'intégration✯

En général, le même compte robot sert à la fois à pull/push dans le pipeline et à alimenter la vue Harbor Registry (qui interroge l'API Harbor pour lister le contenu du projet). Accordez-lui les permissions suivantes :

Ressource → Action	Rôle
Repository → Pull	Récupérer des images dans le pipeline
Repository → Push	Pousser des images depuis le pipeline
Repository → List	Lister les dépôts dans la vue Harbor Registry
Artifact → List + Read	Lister et détailler les artefacts
Tag → List	Lister les tags des artefacts

List/Read ≠ Pull/Push

Les actions de lecture (List, Read) sont distinctes des actions d'image (Pull, Push) : un robot capable de pousser des images ne peut pas pour autant lister les dépôts/artefacts/tags tant que les permissions List/Read ne sont pas explicitement cochées. Sans elles, la vue Harbor Registry reste vide.

Résultats de scan non disponibles

L'intégration Harbor de GitLab n'affiche pas les résultats du scanner de vulnérabilités. Inutile donc d'accorder au robot des permissions Scan pour cet usage : ces rapports se consultent dans l'interface web du registre.

Consulter les artefacts depuis GitLab✯

Une fois l'intégration active, un menu Harbor Registry (sous Deploy / Operate) apparaît dans votre projet GitLab. Il liste les dépôts et les artefacts du projet Harbor associé, sans quitter l'interface GitLab.

Vue Harbor Registry dans GitLab

Pousser une image depuis un pipeline✯

Exemple complet construisant une image avec Docker-in-Docker (dind) et la poussant sur le registre, taguée avec le SHA court du commit puis latest. Les variables $HARBOR_* proviennent de l'intégration Harbor :

build-image:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  variables:
    IMAGE: $HARBOR_HOST/$HARBOR_PROJECT/mon-appli
  before_script:
    - echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin
  script:
    - docker build -t "$IMAGE:$CI_COMMIT_SHORT_SHA" -t "$IMAGE:latest" .
    - docker push "$IMAGE:$CI_COMMIT_SHORT_SHA"
    - docker push "$IMAGE:latest"

Pipeline complet prêt à l'emploi

Un exemple fonctionnel de ce pipeline est disponible dans le dépôt cri-public/gitlab-ci-registry-boilerplate : forkez-le pour partir d'une base qui construit et pousse déjà une image sur le registre.

Récupérer une image depuis un pipeline✯

Dans un job disposant d'un client Docker, authentifiez-vous puis faites un pull :

deploy:
  stage: deploy
  image: docker:27
  services:
    - docker:27-dind
  before_script:
    - echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin
  script:
    - docker pull registry.isima.fr/mon-projet/mon-appli:latest
    - docker run --rm registry.isima.fr/mon-projet/mon-appli:latest --version

Utiliser une image du registre comme image de job✯

GitLab peut exécuter directement un job dans une image issue du registre (clé image:). Utilisez de préférence une image publique ou issue du proxy cache : aucune authentification n'est alors nécessaire, et le proxy cache accélère le téléchargement tout en évitant les rate limits des registres publics.

test:
  image: registry.isima.fr/dh/library/node:20
  script:
    - npm ci
    - npm test

Image issue d'un projet privé

L'image servant de image: à un job est tirée par le runner avant l'exécution du script : les variables de l'intégration Harbor ne sont donc pas encore disponibles à ce moment. Pour utiliser une image d'un projet privé, ne la déclarez pas comme image: du job mais récupérez-la dans le script après authentification (voir Récupérer une image depuis un pipeline).

Utiliser une image du registre comme service✯

Les services (services:) sont des conteneurs annexes démarrés à côté du job — typiquement une base de données pour les tests. Ils peuvent eux aussi provenir du registre, en particulier du proxy cache :

test-avec-bdd:
  image: registry.isima.fr/dh/library/python:3.12
  services:
    - name: registry.isima.fr/dh/library/postgres:16
      alias: db
  variables:
    POSTGRES_DB: testdb
    POSTGRES_USER: runner
    POSTGRES_PASSWORD: secret
    # vu depuis le job, la base est joignable sur l'hôte « db »
    DATABASE_URL: "postgresql://runner:secret@db:5432/testdb"
  script:
    - pip install -r requirements.txt
    - pytest

La clé alias définit le nom d'hôte par lequel le job joint le service (ici db).
Privilégiez des images de service publiques ou issues du proxy cache : comme pour l'image du job, un service est tiré par le runner avant l'exécution du script.

Variables GitLab utiles✯

GitLab expose des variables prédéfinies pratiques pour tagger vos images :

Variable	Description
`$CI_COMMIT_SHORT_SHA`	SHA court du commit (tag d'image idéal)
`$CI_COMMIT_REF_SLUG`	Nom de branche/tag « sluggifié » (utilisable dans un nom d'image)
`$CI_COMMIT_TAG`	Tag Git, lors d'un pipeline déclenché par un tag
`$CI_PIPELINE_IID`	Numéro de pipeline interne au projet