Intégration avec GitLab

  • Publié le May 22, 2026
  • 6 Minute(s) lue(s)
Prev Next

L'intégration GitLab permet de connecter des dépôts hébergés sur une instance GitLab externe à un projet Tuleap. Sans migrer votre code, vous bénéficiez d'une traçabilité complète : chaque commit, Merge Request, tag ou branche GitLab référençant un artifact Tuleap crée automatiquement une référence croisée bidirectionnelle.

Pré-requis

  • Les plugins Git et GitLab doivent être installés et activés.

  • Vous devez être administrateur du service Git dans votre projet Tuleap.

  • Vous devez disposer d'un GitLab Access Token autorisant l'accès à l'API GitLab (scope api requis).

Types de tokens GitLab

Type de token

Portée

Qui est affiché dans les commentaires

Personal access token

Tous les dépôts que vous maintenez

Votre compte GitLab

Group access token

Les dépôts du groupe GitLab

Le bot du groupe

Project access token

Un seul dépôt GitLab

Le bot du projet

Astuce

Les commentaires automatiques ajoutés par Tuleap sur GitLab (backlinks) sont postés avec le compte associé au token. Choisissez un token adapté (project ou group token de préférence) pour éviter que les commentaires soient attribués à un utilisateur personnel.

Enregistrer un dépôt GitLab

Procédure

  1. Accédez au service Git de votre projet Tuleap.

  2. Cliquez sur "Ajouter un dépôt", puis sur "Ajouter un dépôt GitLab".

  3. Dans la modale, saisissez l'URL de votre instance GitLab et le token d'accès.

  4. La liste des dépôts que vous pouvez intégrer s'affiche. Sélectionnez le dépôt à lier.

Une fois enregistré, le dépôt GitLab apparaît dans la liste des dépôts du projet, identifiable par l'icône GitLab.

Lors de l'enregistrement d'un dépôt GitLab, Tuleap crée automatiquement un webhook dans le dépôt GitLab. Ce webhook écoute trois types d'événements :

  • Push : déclenche l'analyse des messages de commit pour créer des références croisées et, le cas échéant, fermer des Artifacts.

  • Merge Request : déclenche la création de références croisées à partir du titre, de la description ou de la branche source de la MR, et met à jour son état dans Tuleap.

  • Tag push : déclenche l'enregistrement du tag et la création de références croisées si le message du tag contient une référence Tuleap.

Attention

Ne modifiez pas les paramètres du webhook manuellement dans GitLab. Si le webhook est supprimé ou altéré, utilisez l'option "Régénérer le webhook" depuis Tuleap.

Gérer un dépôt intégré

En cliquant sur l'icône d'engrenage du dépôt GitLab, vous pouvez :

  • Modifier le token d'accès : si le token a expiré ou a été révoqué. Le webhook est automatiquement régénéré.

  • Régénérer le webhook : si le webhook a été modifié ou supprimé côté GitLab, cette action recrée un webhook fonctionnel avec un nouveau secret.

  • Activer/désactiver la fermeture d'Artifacts : permet aux commits GitLab de fermer automatiquement des Artifacts Tuleap (désactivé par défaut).

  • Modifier le préfixe de branche : définit un préfixe pour les branches créées depuis un Artifact Tuleap (par exemple feature/, fix/).

  • Dissocier le dépôt : supprime le lien entre le dépôt GitLab et le projet Tuleap. Les références existantes sont supprimées et les futurs commits ne créeront plus de références croisées.

Attention

La dissociation ne supprime rien côté GitLab. Elle supprime uniquement le lien dans Tuleap.

Lier un groupe GitLab

Au lieu d'intégrer les dépôts un par un, vous pouvez lier un groupe GitLab entier à votre projet Tuleap. Tous les dépôts du groupe seront automatiquement intégrés.

Information

Un projet Tuleap ne peut être lié qu'à un seul groupe GitLab à la fois.

Procédure

  1. Dans le service Git, accédez à l'onglet d'administration "GitLab Group".

  2. Cliquez sur le bouton pour démarrer l'assistant.

  3. Saisissez l'URL de votre instance GitLab et le token d'accès.

  4. Sélectionnez le groupe à lier dans la liste des groupes visibles.

  5. Configurez les paramètres par défaut pour les dépôts synchronisés :

    • Fermeture automatique d'Artifacts (optionnel).

    • Préfixe de branche (optionnel).

Tous les dépôts du groupe sont intégrés dans le projet Tuleap.

Information

Les paramètres configurés lors de la liaison ne s'appliquent qu'aux nouveaux dépôts lors de la synchronisation. Ils peuvent être modifiés individuellement par dépôt après synchronisation.

Actions disponibles

  • Synchroniser : récupère les nouveaux dépôts ajoutés au groupe GitLab depuis la dernière synchronisation. Les dépôts supprimés ou déplacés côté GitLab ne sont pas retirés automatiquement de Tuleap.

  • Mettre à jour le token : renouvelle le token d'accès si l'ancien a expiré.

  • Modifier la configuration : change les paramètres par défaut pour les prochaines synchronisations.

  • Dissocier le groupe : supprime le lien entre le projet Tuleap et le groupe GitLab. Les dépôts déjà intégrés restent en place ; pour les retirer, dissociez-les individuellement.

Références croisées

Le système de références croisées est le cœur de l'intégration GitLab. Il fonctionne dans les deux sens.

Depuis GitLab vers Tuleap

Pour créer une référence vers un Artifact Tuleap dans GitLab, ajoutez le mot-clé TULEAP-<id_artifact> (sensible à la casse) dans :

Élément GitLab

Où placer la référence

Informations affichées dans Tuleap

Commit

Message de commit

SHA-1, auteur (avatar si email reconnu), message

Merge Request

Titre, description ou nom de la branche source

Titre, auteur, état (ouverte, fusionnée, fermée)

Tag

Message du tag

Nom du tag, message, SHA-1 du commit associé

Branche

Nom de la branche

Nom de la branche, SHA-1, date du dernier push

Vous pouvez référencer plusieurs Artifacts dans un même commit ou MR. En revanche, une branche ne peut référencer qu'un seul Artifact.

Information

Côté GitLab, un commentaire automatique (backlink) est ajouté sur les commits et Merge Requests contenant des références Tuleap. Ce commentaire liste les Artifacts référencés avec des liens cliquables vers Tuleap. Il est posté avec le compte associé au token d'accès configuré lors de l'enregistrement du dépôt. Ce n'est pas possible pour les tags et branches.

Depuis Tuleap vers GitLab

Depuis n'importe quel champ de texte Tuleap (suivi d'Artifact, commentaire, etc.), utilisez les mots-clés suivants :

Mot-clé

Syntaxe

Cible

gitlab_commit

gitlab_commit #<repo>/<sha1>

Commit GitLab

gitlab_mr

gitlab_mr #<repo>/<mr_id>

Merge Request GitLab

gitlab_tag

gitlab_tag #<repo>/<tag_name>

Tag GitLab

gitlab_branch

gitlab_branch #<repo>/<branch_name>

Branche GitLab

Le <repo> doit correspondre à un dépôt GitLab enregistré dans le projet. En cliquant sur la référence, vous êtes redirigé vers l'élément correspondant sur votre instance GitLab.

Fermer des Artifacts depuis GitLab

Si l'option est activée sur le dépôt intégré, les commits GitLab peuvent fermer automatiquement des Artifacts Tuleap.

Plusieurs conditions sont nécessaires :

  • L'option "Autoriser la fermeture des artifacts" est activée sur le dépôt intégré.

  • Le push a lieu sur la branche par défaut du dépôt GitLab.

  • L'Artifact appartient au même projet que l'intégration.

  • La sémantique "Done" ou sémantique "Status" est définie.

  • L'Artifact n'est pas déjà fermé.

Mots-clés de fermeture

Les mots-clés utilisables pour la fermeture d’artifact sont les mêmes que pour Tuleap Git, mais associés au format TULEAP-<id> :

  • Closes TULEAP-1234

  • Fixes TULEAP-1234

  • Resolves TULEAP-1234

  • Implements TULEAP-1234

Et leurs variantes : Close, Closed, Closing, Fix, Fixed, Fixing, etc.

Créer une branche GitLab depuis un Artifact

Vous pouvez créer une branche GitLab et, optionnellement, la Merge Request associée directement depuis un Artifact Tuleap.

Plusieurs conditions sont nécessaires :

  • Au moins un dépôt GitLab est intégré dans le projet de l'Artifact avec un token valide.

  • Vous êtes membre du projet.

  • Vous avez accès en lecture à l'Artifact.

Procédure

  1. Ouvrez un Artifact.

  2. Dans les actions de l'Artifact, sélectionnez "Créer une branche dans un dépôt GitLab".

  3. Sélectionnez le dépôt GitLab cible.

  4. La branche est créée automatiquement avec le format : (préfixe)TULEAP-{id_artifact}.

Information

Le préfixe de branche est configurable par dépôt depuis les paramètres de l'intégration GitLab.

Créer une Merge Request

Une fois la branche créée et vos modifications poussées, vous pouvez créer une Merge Request GitLab depuis le même Artifact Tuleap. La MR est automatiquement configurée :

  • Titre : TULEAP-{id_artifact}: {titre de l'Artifact}.

  • Branche cible : la branche par défaut du dépôt GitLab.

  • État initial : la MR est créée en mode brouillon (draft).

La Merge Request apparaît alors dans les références croisées de l'Artifact, avec son état affiché en temps réel (ouverte, fusionnée, fermée).

Limitations connues

  • Si vous avez déjà une référence de projet nommée gitlab_commit, gitlab_mr, gitlab_tag ou gitlab_branch, elle remplacera celle utilisée par le plugin.

  • Tuleap affiche le path_with_namespace du dépôt (pas le name_with_namespace).

  • Deux dépôts avec le même nom et chemin provenant de deux instances GitLab différentes ne peuvent pas être intégrés dans le même projet Tuleap.

  • Le nom de projet et le namespace GitLab ne doivent pas contenir de - ni de ..

Articles Liés