Configurer Xsquash4GitLab dans Squash TM

Le plugin Xsquash4GitLab est un plugin Squash TM dédié à la synchronisation de tickets depuis GitLab. Il s'articule autour de deux fonctionnalités principales :

Un module de synchronisation automatique qui permet à Squash TM d’importer et de maintenir automatiquement à jour des issues GitLab sous forme d’exigences synchronisées dans l’espace Exigences.
Un module de reporting qui permet d’afficher sur les issues GitLab des informations concernant le déroulement de la recette dans Squash TM. Ces informations sont affichées dans des notes sur les issues GitLab qui sont créées et mises à jour par Squash TM.

Une partie des fonctionnalités du plugin sont automatiques et se déclenchent seulement une fois la configuration complète effectuée :

Nom	Déclenchement	Sens de circulation
Synchronisation des issues GitLab	Automatique une fois la configuration faite	De GitLab vers Squash TM
Reporting des données de recette Squash TM	Automatique une fois la configuration faite	De Squash TM vers GitLab

Attention

Lors des opérations automatiques, le plugin n’effacera jamais d’exigences synchronisées dans Squash TM ou d'issues dans GitLab. Si des issues venaient à être supprimées ou déplacées dans GitLab, les exigences correspondantes resteront dans Squash TM et devront éventuellement être supprimées manuellement par les utilisateurs de Squash TM si nécessaire.

Cette page est dédiée à la configuration du plugin Xsquash4GitLab depuis l'Administration Squash TM.
Pour en savoir plus sur les exigences synchronisées, consulter la page suivante : Synchroniser des objets agiles GitLab dans Squash.

Installation et prérequis

Info

Le plugin Xsquash4GitLab est disponible gratuitement. Il est à télécharger et installer sur Squash TM. Pour l'utiliser, il nécessaire d'installer également le plugin GitLab Bugtracker.
Consulter les pages suivantes pour en savoir plus : Téléchargements et Installer les plugins Squash TM.

Communication Squash TM/GitLab

Le plugin Xsquash4GitLab est un plugin reposant sur une communication bidirectionnelle entre Squash TM et GitLab. Il s’agit d’une communication de serveur à serveur, passant essentiellement par l’API GraphQL de GitLab. Pour que le plugin puisse fonctionner, il faut que la communication soit possible ce qui nécessite souvent des interventions sur l’infrastructure réseau : ouverture de flux dans les firewalls, ajout de certificats dans les JVM, etc.

Si le même serveur GitLab est déjà utilisé avec succès en tant que bugtracker au moyen du plugin GitLab Bugtracker, la communication est déjà possible.

En cas de problème, il faut effectuer un test directement sur le serveur Squash TM pour vérifier si GitLab est accessible : essayer de passer une requête vers l’API GraphQL GitLab directement depuis le serveur hébergeant Squash TM au moyen d’un curl ou un wget. Si la requête ne passe pas, c’est un problème réseau.

Permissions du compte GitLab

Pour fonctionner, le plugin doit pouvoir communiquer avec GitLab au travers d’au moins un utilisateur GitLab. Cet utilisateur doit avoir à minima des droits en lecture par l’API sur l’ensemble des tickets à synchroniser. Si le reporting de Squash vers GitLab est activé, l’utilisateur doit impérativement avoir des droits en écriture par l’API sur l’ensemble de ces tickets concernés.

Création du serveur Xsquash4GitLab dans Squash TM

Pour utiliser le plugin Xsquash4GitLab, il faut déclarer un serveur de synchronisation de type gitlab.bugtracker dans l'espace Serveurs>Bugtrackers et serveurs de synchronisation de l'Administration Squash TM.

Dans la pop-up de création d'un nouveau serveur, renseigner le nom du serveur (nom libre), le type gitlab.bugtracker et l'URL de GitLab la plus simple possible puis ajouter.

Ajouter un serveur Xsquash4GitLab

Attention

Un serveur de synchronisation Xsquash4GitLab ne peut être supprimé s'il est utilisé pour réaliser des synchronisations. Il faut supprimer au préalable les synchronisations avant de pouvoir supprimer le serveur.

Identifiants utilisés pour les synchronisations

Le plugin utilise l'API GraphQL de GitLab pour récupérer les données via une authentification de type "Token Authentication" avec le token d'un compte GitLab.

Pour des raisons de sécurité, les logins et mots de passe saisis pour la connexion aux outils tiers sont chiffrés dans la base de données avec une clé de chiffrement. Le plugin Xsquash4GitLab possède également deux propriétés à configurer directement dans le fichier de configuration de Squash TM squash.tm.cfg.properties. Pour en savoir plus, consulter la page suivante : Gestion du fichier de configuration Squash TM.

Compte technique

Cette option permet d'effectuer toutes les synchronisations avec le même compte GitLab. Dans ce cas, la bonne pratique conseillée est de créer un compte technique dédié au plugin dans GitLab qui dispose des droits nécessaires uniquement sur les groupes et/ou projets GitLab souhaités.

Ensuite, sur la page de configuration du serveur de synchronisation, dans le bloc Politique d'authentification, il est nécessaire de renseigner le token généré dans GitLab pour le compte technique dans la partie Identifiants du compte technique.

Page serveur Xsquash4GitLab

Configuration de Xsquash4GitLab sur un projet

Les synchronisations d'issues GitLab se configurent individuellement pour chaque projet Squash TM. Cette configuration se fait au niveau de l'ancre Plugins Plugins de la page de consultation d'un projet.

Il faut commencer par activer le plugin Connecteur Xsquash4GitLab pour pouvoir accéder à sa page de configuration spécifique depuis le bouton Configurer .

Pour désactiver l'utilisation du plugin sur le projet, il suffit de cliquer sur le même bouton que pour l'activer. L’option Conserver la configuration du plugin permet de sauvegarder durant la désactivation du plugin la configuration et les synchronisations du projet lorsqu'elle est cochée. Si l’option est décochée, la configuration et les synchronisations du projet sont définitivement supprimées à la désactivation du plugin.

Désactiver Xsquash4GitLab

La page de configuration de Xsquash4GitLab est accessible en cliquant sur le bouton Configurer présent en bout de ligne du Connecteur Xsquash4GitLab.

Elle se compose de quatre blocs :

le bloc Synchronisations qui permet de configurer le périmètre des synchronisations ;
le bloc Équivalences entre les champs qui permet de configurer les équivalences entre les champs GitLab et les champs Squash TM ;
le bloc Équivalences entre les valeurs des champs qui permet de configurer les équivalences de valeurs pour les champs de type liste : Criticité, Catégorie et Statut ;
le bloc Suivi de l'avancement des tests dans GitLab qui permet d'activer ou désactiver l'affichage du suivi de l'avancement des tests dans les issues GitLab.

Configuration des synchronisations

Une synchronisation est l’unité de travail du plugin Xsquash4GitLab. Elle représente l’ensemble des issues GitLab définies par un périmètre dynamique qui sont récupérées dans Squash TM. Ce périmètre dynamique est recalculé à chaque processus de mise à jour. Par défaut, le délai est de cinq minutes entre chaque processus de synchronisations.

Le périmètre de synchronisation est défini par deux éléments :

l'emplacement des issues : il correspond au groupe ou projet dans lequel se trouvent les issues à synchroniser ;
le type de synchronisation : pour l'emplacement sélectionné, il permet de définir si les issues à synchroniser doivent correspondre à des filtres appliqués sur leurs champs ou se trouver dans un board GitLab.

Voici le périmètre récupéré en fonction du type de synchronisation choisi :

Emplacement des issues	Type de synchronisation	Périmètre de synchronisation	Note
Groupe ou Projet	Filtres sur les issues	L'ensemble des issues du groupe ou projet qui correspondent aux filtres appliqués sur leurs champs. Dans le cas où l'emplacement sélectionné est un groupe, les issues renvoyées sont celles contenues dans les projets du groupe sélectionné.	Le contrôle du périmètre est effectué côté Squash TM.
Groupe ou Projet	Board	L’ensemble des issues contenues dans un tableau du groupe ou projet sélectionné, en tenant compte de sa configuration.	Le contrôle du périmètre est délégué à GitLab. Si la configuration du tableau est modifié côté GitLab, le périmètre dans Squash TM est modifié, sans préavis ni message. Si le tableau est supprimé dans GitLab, la synchronisation échoue avec un message dans les logs.

Créer une synchronisation

Pour créer une synchronisation, cliquer sur le bouton Ajouter présent au sommet du bloc Synchronisations.

Ajout synchro

Le tableau suivant détaille le fonctionnement des champs de la pop-up et comment les renseigner :

Nom	Obligatoire	Modifiable	Commentaire
Nom	Oui	Oui	Nom libre. Il doit être unique sur l'ensemble de l'instance Squash TM.
Chemin Cible	Oui	Non	Chemin initial du répertoire cible de la synchronisation. Ce répertoire ne doit pas exister dans l’espace Exigences, il est créé par Xsquash4GitLab au premier cycle de synchronisation. Ce chemin ne doit pas commencer par un / (ex : dossier 1/sous-dossier 1).
Serveur	Oui	Non	Serveur Xsquash4GitLab utilisé pour cette synchronisation, à choisir dans la liste des serveurs paramétrés dans l’écran d’administration des Bugtrackers et serveurs de synchronisation.
Périmètre	Oui	Non	Chemin du groupe, sous-groupe ou projet où se trouvent les issues à synchroniser. Il doit être indiqué tel qu'il apparaît dans l'URL de GitLab (ex : groupe-1/sous-groupe-1/projet-1 pour synchroniser les issues du "Projet 1", ou groupe-1 pour synchroniser les issues des projets contenus dans le "Groupe 1").
Sélection par	Oui	Non	Type de synchronisation. Deux options possibles : Issue ou Board. En fonction de l'option choisie, les champs suivants de la pop-up changent.
Board	Oui	Oui	Tableau à synchroniser. S'affiche uniquement si le champ 'Périmètre' est renseigné et pour les synchronisations par Board
Organisation par	Oui	Non	Manière dont sont organisées les issues synchronisées dans la bibliothèque des exigences de Squash TM. Quatre options possibles selon le type de synchronisation : - À plat (Issue) : toutes les issues GitLab sont synchronisées à la racine du répertoire de synchronisation - Iteration (Issue et Board) : un répertoire est créé pour chaque iteration contenue dans le périmètre - Milestone (Issue et Board) : un répertoire est créé pour chaque milestone contenu dans le périmètre - Arborescence (Issue) : dans le cas où le périmètre est un groupe, un répertoire est créé pour chaque sous-groupe et projet
Filtres actifs	Non	Oui	Permet d’affiner le périmètre en appliquant des filtres sur les champs des issues. Permet notamment de limiter la synchronisation à l'itération ou milestone en cours. Disponible uniquement pour les synchronisations par Issue

Simuler une synchronisation

Lors de l'ajout d'une nouvelle synchronisation, il est possible d'effectuer une simulation de la synchronisation avant de confirmer sa création.

Pour cela, un bouton [Simuler] figure dans la fenêtre d'ajout de synchronisation. Il permet de visualiser le nombre et le détail des tickets que contient la synchronisation pour vérifier que cela correspond au périmètre voulu.

Simulation synchro

Suivi des synchronisations

Une fois la synchronisation configurée, une ligne supplémentaire apparaît dans la table des synchronisations. À la prochaine mise à jour, l’ensemble des exigences synchronisées qui correspondent au périmètre sont créées. Si la synchronisation échoue sur une erreur, rien n'est créé dans Squash TM. Le statut de chaque synchronisation est affiché dans la table des synchronisations.

Le bouton permet de rafraîchir la page de configuration pour voir si le statut des synchronisations a été mis à jour suite au passage du processus de mise à jour.

Forcer une synchronisation complète

Par défaut, le plugin ne met à jour que les exigences synchronisées qui ont été modifiées dans GitLab depuis le dernier processus de mise à jour connu et en succès.
Dans le cas d’un changement d’équivalences de champ ou de valeur côté Squash TM, il est nécessaire de resynchroniser l’ensemble des exigences côté Squash TM, même si rien n’a changé côté GitLab. Le bouton Forcer la synchronisation permet de forcer la mise à jour de l’ensemble des issues synchronisées qui sont dans le périmètre actuel d’une ou plusieurs synchronisations.

Info

Afin d’éviter des processus de mises à jour inutiles, il est conseillé de faire les équivalences avant de déclarer les synchronisations.
Si les équivalences doivent évoluer par la suite, il est conseillé de faire toutes les évolutions d’équivalences de champs et de valeurs, puis de forcer une seule fois toutes les synchronisations du projet.

Désactiver une synchronisation

Le bouton présent en début de ligne permet de désactiver ou de réactiver une synchronisation sans la supprimer. Lorsqu’une synchronisation est désactivée, les issues présentes dans son périmètre ne sont plus synchronisées. La ligne est grisée et n’est plus modifiable mais il est toujours possible de supprimer la synchronisation.
Lorsqu’elle est réactivée, les issues sont de nouveau synchronisées dans Squash TM et reprennent les attributs de synchronisation ainsi que les équivalences et le reporting définis dans les autres blocs.

Supprimer une synchronisation

Le bouton permet de supprimer une ou plusieurs synchronisations. En accord avec la politique de non-suppression, les exigences synchronisées ne sont pas supprimées mais transformées en exigences natives de Squash TM (affichées en noir). Elles ne sont plus mises à jour depuis GitLab et se comportent comme n’importe quelle autre exigence de Squash TM. Il en va de même pour tous les répertoires synchronisés (répertoires cibles et répertoires d'iterations, milestones et projets).
Si l’utilisateur désire supprimer ces exigences, il doit le faire manuellement comme pour n’importe quelle exigence de Squash TM.

Configurer les équivalences de champs

Afin de permettre à Squash TM d’afficher les informations contenues dans les champs des issues GitLab, il faut configurer des équivalences de champs. Cette configuration se fait dans le deuxième bloc de l'écran de configuration Xsquash4GitLab.

Le bouton Ajouter présent au sommet du bloc permet d'ajouter une nouvelle équivalence.

Equivalence entre les champs

Les champs Squash TM disponibles sont présentés dans une liste déroulante. Il est possible d'enrichir cette liste en ajoutant des champs personnalisés aux exigences du projet. Il est recommandé d'utiliser des champs personnalisés Squash TM de type "Texte simple" ou "Tag" pour récupérer les données des issues GitLab dans la majeure partie des cas.

Pour en savoir plus sur les champs personnalisés, consulter la page suivante : Gérer les champs personnalisés.

Les champs GitLab disponibles sont également présentés dans une liste déroulante. Le même champ GitLab peut être mappé avec plusieurs champs Squash TM. Certaines équivalences sont renseignées par défaut et ne peuvent pas être modifiées et/ou supprimées.

Une fois la configuration du bloc terminée, il ne faut pas oublier de bien forcer les synchronisations du projet pour que la modification soit prise en compte. Il est également nécessaire de forcer la synchronisation après une suppression d'équivalence dans le tableau sans quoi des erreurs apparaissent dans les logs.

Info

Certains champs GitLab présents dans la liste déroulante ne sont disponibles qu'avec GitLab Premium ou Ultimate. Si une équivalence est renseignée pour l'un de ces champs avec GitLab Community, la synchronisation du champ sera ignorée.

Configurer les équivalences des valeurs de champs

Dans GitLab, la majorité des informations d'une issue est définie sous forme de labels ou de labels scopés dans un unique champ. C'est le cas notamment de la criticité, du statut et de la catégorie.

Si une équivalence a été configurée entre le champ GitLab Labels et les champs Squash TM Criticité, Catégorie ou Statut dans le bloc Configurer les équivalences de champs, il est possible de configurer des équivalences entre les valeurs de ces champs pour avoir un mapping complet. Celle-ci s’effectue dans le troisième bloc de l’écran.

Cette configuration utilise la syntaxe YAML. Il est donc indispensable de bien respecter le format indiqué dans l'aide à la configuration.

Dans l'aide à la configuration :

champsquash correspond au nom du champ Squash TM en anglais en minuscule comme affiché dans la liste des champs et valeurs disponibles à la fin de l'aide ;
valeurgitlab est la valeur du label GitLab tel qu'il a été défini dans GitLab, en respectant la casse. Pour les labels scopés, il faut les écrire sous la forme clé::valeur ;
valeursquash est la valeur du champ Squash TM telle qu'affichée dans la liste des champs et valeurs disponibles à la fin de l'aide.

Voici un exemple de configuration pour ces trois champs :

Equivalence entre les valeurs de champs

Une fois la configuration du bloc terminée, il ne faut pas oublier de bien forcer les synchronisations du projet pour que la modification soit prise en compte. Il est également nécessaire de forcer la synchronisation après une suppression d'équivalence.

Il est possible d'associer une liste personnalisée au champ Catégorie des exigences du projet pour récupérer la valeur des types de tickets Jira dans Squash TM comme dans l'exemple ci-dessus.
Pour en savoir plus sur les listes personnalisées, consulter la page suivante : Gérer les listes personnalisées.

Attention

Les statuts "Approuvé" et "Obsolète" bloquent toutes modifications sur une exigence.
Si un mapping est fait avec ces deux statuts, les exigences qui prendront ces statuts automatiquement ne seront plus mises à jour par la suite.
Il faudra modifier le statut manuellement à "En cours de rédaction" ou "À approuver" pour réactiver la mise à jour de l'exigence.

Configurer le reporting de Squash TM vers GitLab

Le plugin Xsquash4GitLab est capable de remonter vers GitLab des informations relatives à la recette réalisée dans Squash TM. Ces informations sont reportées directement au niveau des issues GitLab sous forme de commentaire.

Quatre informations sont disponibles : trois taux d’avancement de la recette (Rédaction des cas de test, Vérification des tickets Jira, Validation des tickets Jira) et un indicateur qui présente une analyse synthétique de ces trois taux : le Statut de la recette.

Ce reporting est optionnel. Il s'effectue dans le bloc Suivi de l'avancement des tests où il est possible de l'activer ou de le désactiver.
S'il est activé, un commentaire est créé dans chaque issue GitLab synchronisée. Ce commentaire est ensuite mis à jour lors d'un cycle de synchronisation, uniquement si les valeurs des indicateurs ont évolué.
S'il est désactivé, rien n'est créé dans GitLab. En revanche, si le reporting était précédemment activé, sa désactivation n'entraîne pas la suppression des commentaires existants.

Champs de reporting Squash vers Jira

Attention

Pour que le reporting dans GitLab fonctionne, il nécessaire de configurer l'URL publique de Squash TM. Cette action ne peut être effectuée que par un administrateur. La procédure est indiquée sur la page URL publique de Squash.

Configurer la synchronisation en temps réel

Les issues GitLab peuvent être synchronisées en temps réel dans Squash TM, sans attendre le prochain cycle de synchronisation.

La configuration s'effectue dans GitLab et s'appuie sur un système de webhook.

Le bloc Synchronisation en temps réel permet de copier les informations à indiquer sur la page d'intégration dans GitLab :

URL du webhook : pour voir cette URL, l'URL publique de Squash TM doit être configurée ;
Jeton secret : facultatif, uniquement si un jeton a été configuré dans le fichier de propriétés de Squash TM par un administrateur système. Selon la configuration, il s'affiche ou non dans l'IHM.

Dans GitLab, la configuration s'effectue au niveau d'un projet, d'un groupe, ou d'une instance (pour les instances GitLab Self-Managed). La procédure suivante décrit la configuration au niveau d'un projet :

dans la barre en haut de l'écran, cliquer sur Main menu > Projects et sélectionner le projet à configurer ;
dans la barre latérale, cliquer sur Settings > Integrations ;
sélectionner Squash TM ;
vérifier que la case Active est cochée ;
dans la partie Trigger, indiquer quel type d'issue est concerné par la synchronisation en temps réel ;
dans le champ Squash TM webhook URL, coller l'URL du webhook ;
dans le champ Secret token (optional), coller le jeton secret (uniquement si un jeton a été configuré dans Squash TM) ;
sauvegarder la configuration.