Configurer Xsquash4GitLab dans Squash TM

Info

Cette page est dédiée à la configuration générale du plugin Xsquash4GitLab. Pour la configuration des synchronisations en elles-mêmes, consulter la page Gérer les synchronisations Xsquash4GitLab dans Squash TM.
Pour en savoir plus sur les fonctionnalités de Xsquash4GitLab, consulter la page Synchroniser des objets agiles GitLab dans Squash.

Le plugin Xsquash4GitLab est un plugin Squash TM dédié à la synchronisation d'issues depuis GitLab. Il s'articule autour des fonctionnalités suivantes :

• 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 ;
  • des milestones et itérations GitLab ainsi que leur contenu sous forme de sprints synchronisés dans l'espace Exécutions. Cette fonctionnalité permet de voir dans l'espace Exécutions les issues d'un sprint à valider et d'alimenter automatiquement le plan d'exécution du sprint avec les tests associés aux issues ;
• 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
Synchronisation des milestones et itérations 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
Créer un plan de test dans Squash à partir d'objets GitLab	Manuel, depuis l'espace Exécutions de Squash TM	De GitLab vers Squash TM

Attention

Lors des opérations automatiques, le plugin n'effacera jamais d'objets synchronisés dans Squash TM (exigences et sprints) ou d'objets dans GitLab (issues, milestones et itérations). Si des objets venaient à être supprimés ou déplacés dans GitLab, les objets synchronisés correspondants resteront dans Squash TM et devront être supprimés manuellement par les utilisateurs de Squash TM si nécessaire.

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 objets à synchroniser (issues, milestones et itérations). 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 des issues concernées.

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.

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.

En savoir plus

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.

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 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 .

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.

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

Elle se compose des blocs suivants :

• le bloc Synchronisations qui permet de configurer le périmètre des synchronisations (consulter la page détaillée Gérer les 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 ;
• le bloc Synchronisation en temps réel qui donne les informations nécessaires pour configurer dans GitLab la synchronisation des issues en temps réel dans 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 présent au sommet du bloc permet d'ajouter une nouvelle équivalence.

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.

En savoir plus

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 :

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.

En savoir plus

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 d'issues GitLab 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 issues GitLab, Validation des issues GitLab) 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.

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 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 :

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