Guide pratique pour l’intégration de GitHub avec IKAN ALM

Introduction

La fonctionnalité de Suivi des Incidents d’IKAN ALM permet de relier des Incidents d’un Système de Suivi des Incidents externe à une Requête de niveau IKAN ALM.

Les Incidents peuvent être reliés à une Requête de niveau de l’une des manières suivantes:

via une recherche automatique d’Incidents traités dans les commentaires fournis par les développeurs lors des processus d’enregistrement (commit) et de chargement (check in) des codes Sources dans le RCV. Cette recherche automatique se fait dans une phase séparée pendant l’exécution d’une Requête de niveau de Construction et se base sur une expression régulière décrivant le format du numéro de l’Incident. Pour le moment, cela n’est supporté que pour les Référentiels de contrôle de version Subversion, Git, Team Foundation et CVS.
via l’énumération des Incidents résolus au moment de délivrer vers les Niveaux de Test/Production, facilitant ainsi la génération de Notes de Réalisation.
en ajoutant manuellement l’Incident à une Requête de niveau réussie dans l’écran Informations détaillées.

Un lien permettant de passer directement de l’Incident dans IKAN ALM vers l’Incident dans l’outil de Suivi des Incidents externe est disponible si l’outil externe dispose d’une interface Web.

En plus de cette fonctionnalité de Suivi des Incidents de base, IKAN ALM offre une intégration plus avancée pour Atlassian Jira, Microsoft Team Foundation Server (TFS), MicroFocus ALM et GitHub avec les fonctionnalités additionnelles suivantes:

la possibilité de tester la connexion avec le Système de Suivi des Incidents au moment de la création ou de la modification d’une définition de Système de Suivi des Incidents.
la synchronisation automatique des incidents traités dans le Système de Suivi des Incidents: IKAN ALM récupère des informations additionnelles, telles que la description, le propriétaire, la priorité, … de l’Incident (Issue) Jira, de l’élément de travail (Work Item) Team Foundation, du Défaut (Defect) MF ALM ou de l’incident (Issue) GitHub correspondant. Ces informations seront synchronisées chaque fois que le résultat de construction évoluera dans le Cycle de vie IKAN ALM.
synchronisation manuelle des Incidents associés à une Requête de niveau dans l’onglet "Incidents" de la fenêtre Informations détaillées.
possibilité d’ajouter automatiquement un commentaire pour un incident/défaut/artefact dans Jira/TFS/MF ALM/GitHub après une Requête de niveau réussie. Ce commentaire contiendra un lien vers la Requête de niveau dans IKAN ALM.

Dans ce document, nous nous concentrerons sur la façon d’effectuer l’intégration de GitHub avec IKAN ALM. D’abord, nous décrirons comment il faut configurer GitHub pour qu’IKAN ALM puisse s’y connecter. Après, nous expliquerons comment créer un Système de Suivi d’incidents représentant votre système GitHub dans IKAN ALM. Ensuite, nous décrirons les étapes à suivre pour activer l’intégration de GitHub dans un Projet IKAN ALM. Finalement, nous donnerons des informations de référence sur l’intégration d’IKAN ALM avec des Systèmes de Suivi des Incidents en général.

Configuration GitHub et prérequis

Générer un Jeton d’API

GitHub nécessite un Jeton d’API pour l’authentification avec son REST API. Pour générer un Jeton pour GitHub:

Allez vers https://github.com/settings/tokens.
Connectez-vous avec l’utilisateur que vous voulez utiliser pour l’authentification avec GitHub.
Cliquez sur "Créer un Jeton d’API".
Entrez un nom mémorisable, choissez une date d’expiration, sélectionnez la portée de "référentiel" et cliquez sur le bouton "Créer".
Copiez ce Jeton dans quelque chose de sécurisé. Vous en aurez besoin plus tard.

Créer un Système de Suivi des Incidents dans IKAN ALM

Dans IKAN ALM, vous devez d’abord créer le Système de Suivi des Incidents qui représente votre système GitHub avant que vous ne puissiez l’assigner et l’utiliser dans un Projet IKAN ALM.

Connectez-vous comme Administrateur IKAN ALM et sélectionnez Administration globale > Suivi des Incidents > Créer un Système de Suivi des Incidents.

L’écran Créer un Système de Suivi des Incidents s’affiche:

Complétez les champs dans le panneau Créer un Système de Suivi des Incidents. Les champs marqués d’un astérisque sont obligatoires.

Champ Description

Champ	Description
Nom	Le nom du Système de Suivi des Incidents, comme par exemple "GitHub_X"
Classe «Plugin Factory»	Le nom complet de la Classe Java qui peut produire des implémentations de l’extension de Système de Suivi des Incidents IKAN ALM. Vous pouvez sélectionner une des valeurs de la liste ou saisir votre propre nom de Classe Pour GitHub, sélectionnez "be.ikan.scm4all.plugin.issuetracking.github.GitHubITSPluginFactory"
Description	Une description significative, comme par exemple "Système de Suivi des Incidents GitHub pour le projet X"
URL	L’URL direct vers les détails d’un seul Incident. Dans cet URL, la clé de l’Incident est représentée par la variable ${issueId}. Pour GitHub, cet URL devra prendre la forme de: `https://github.com/ORGANIZATION/REPOSITORY/issues/${issueId}` ORGANISATION et REPOSITORY dépendent des paramètres de votre Référentiel GitHub.
Utilisateur	L’Utilisateur GitHub utilisé par IKAN ALM pour se connecter à GitHub
Mot de passe	Le Mot de passe de l’utilisateur GitHub utilisé par IKAN ALM pour se connecter à GitHub Celui-ci peut être laissé vide puisque GitHub ne supporte plus l’authentification par Mot de passe, désormais.
Modèle de recherche de Suivi d’Incident	Ce champ doit contenir une expression régulière qu’IKAN ALM utilisera pour trouver les clés d’incidents dans les messages saisis lors de l’enregistrement dans le RCV. Le Modèle de recherche de Suivi d’Incident sert à retrouver une référence vers un Incident dans le texte enregistré. Depuis que GitHub uitlise le même format pour lister les Incidents de tous les utilisateurs, le modèle de recherche d’Incident devra être toujours "#[0-9]+".
Modèle d’Identifiant de Suivi d’Incident	Ce champ doit contenir une expression régulière qu’IKAN ALM utilisera pour trouver les clés d’incidents dans les messages saisis lors de l’enregistrement dans le RCV. Le Modèle d’Identifiant de Suivi d’Incident sert à retrouver l’identifiant de l’Incident (ou la clé) dans la référence de l’Incident correspondant. Depuis que GitHub uitlise le même format pour lister les Incidents de tous les utilisateurs, le modèle d’Incident devra être toujours `[0-9]+`.
Ajouter des Commentaires	Si vous établissez cette option à "Oui", IKAN ALM ajoutera un commentaire à l’Incident au moment où il est associé à une Requête de niveau IKAN ALM. Des explications plus détaillées suivent plus loin dans ce document.

Nom

Le nom du Système de Suivi des Incidents, comme par exemple "GitHub_X"

Classe «Plugin Factory»

Le nom complet de la Classe Java qui peut produire des implémentations de l’extension de Système de Suivi des Incidents IKAN ALM.

Vous pouvez sélectionner une des valeurs de la liste ou saisir votre propre nom de Classe

Pour GitHub, sélectionnez "be.ikan.scm4all.plugin.issuetracking.github.GitHubITSPluginFactory"

Description

Une description significative, comme par exemple "Système de Suivi des Incidents GitHub pour le projet X"

URL

L’URL direct vers les détails d’un seul Incident. Dans cet URL, la clé de l’Incident est représentée par la variable ${issueId}.

Pour GitHub, cet URL devra prendre la forme de: https://github.com/ORGANIZATION/REPOSITORY/issues/${issueId}

ORGANISATION et REPOSITORY dépendent des paramètres de votre Référentiel GitHub.

Utilisateur

L’Utilisateur GitHub utilisé par IKAN ALM pour se connecter à GitHub

Mot de passe

Le Mot de passe de l’utilisateur GitHub utilisé par IKAN ALM pour se connecter à GitHub

Celui-ci peut être laissé vide puisque GitHub ne supporte plus l’authentification par Mot de passe, désormais.

Modèle de recherche de Suivi d’Incident

Ce champ doit contenir une expression régulière qu’IKAN ALM utilisera pour trouver les clés d’incidents dans les messages saisis lors de l’enregistrement dans le RCV. Le Modèle de recherche de Suivi d’Incident sert à retrouver une référence vers un Incident dans le texte enregistré.

Depuis que GitHub uitlise le même format pour lister les Incidents de tous les utilisateurs, le modèle de recherche d’Incident devra être toujours "#[0-9]+".

Modèle d’Identifiant de Suivi d’Incident

Ce champ doit contenir une expression régulière qu’IKAN ALM utilisera pour trouver les clés d’incidents dans les messages saisis lors de l’enregistrement dans le RCV. Le Modèle d’Identifiant de Suivi d’Incident sert à retrouver l’identifiant de l’Incident (ou la clé) dans la référence de l’Incident correspondant.

Depuis que GitHub uitlise le même format pour lister les Incidents de tous les utilisateurs, le modèle d’Incident devra être toujours [0-9]+.

Ajouter des Commentaires

Si vous établissez cette option à "Oui", IKAN ALM ajoutera un commentaire à l’Incident au moment où il est associé à une Requête de niveau IKAN ALM. Des explications plus détaillées suivent plus loin dans ce document.

Après avoir complété les champs, cliquez sur le bouton Créer.

Vous serez réorienté vers l’écran de modification du Système de Suivi des Incidents nouvellement créé et un avertissement s’affichera en haut de la fenêtre.

Cet avertissement s’affiche parce l’extension du Système de Suivi des Incidents GitHub requiert que les propriétés suivantes soient spécifiées: gitHubRESTUrl et gitHubPersonalAccessToken. gitHubRESTUrl représente l’URL de l’API GitHub REST et IKAN ALM en a besoin pour établir la connexion avec GitHub. gitHubPersonalAccessToken représente le Jeton d’accès généré durant la préparation de GitHub et est nécessaire pour établir la connexion avec GitHub.
Ensuite, cliquez sur le lien "Créer", le lien à côté de la proprièté gitHubRESTUrl.
Spécifiez la valeur de l’URL de l’API REST de GitHub.

La valeur valide de ce point d’accès est toujours du format: https://api.github.com/repos/${ORGANISATION}/${REPOSITORY}, avec ORGANISATION et REPOSITORY qui dépendent des paramètres de votre Référentiel GitHub.
Cliquez sur le bouton Créer pour confirmer la création de la Propriété et fermer le dialogue.
Répétez les étapes 4 à 6 pour la propriété gitHubPersonalAccessToken, en utilisant le Jeton d’Accès Personnel généré pendant la préparation de GitHub.
Le message d’alerte au sujet des valeurs manquantes doit avoir disparu maintenant.
Testez si IKAN ALM peut se connecter avec votre système GitHub en cliquant sur le bouton Vérifier la connexion.

Si le test échoue, corrigez les erreurs spécifiées dans la trace de pile et refaites le test.

Le Système de Suivi des Incidents GitHub étant défini, nous pouvons l’utiliser dans nos Projets IKAN ALM.

Pour cela, nous devons associer le Système de Suivi des Incidents à un Projet.

Associer un Système de Suivi des Incidents à un Projet

Connectez-vous comme un Utilisateur IKAN ALM avec des droits d’accès d’Administrateur sur le Projet que vous voulez y associer.
Naviguez vers Administration des projets et sélectionnez le Projet approprié dans l'Aperçu des Projets.
En-dessous du panneau Infos Projet:, cliquez sur le bouton Modifier.
Dans le champ "Système de Suivi des Incidents", sélectionnez le Système de Suivi des Incidents créé à partir du menu déroulant et cliquez sur le bouton Enregistrer.

Ensuite, nous devons ajouter la Phase "Suivi des Incidents" à chaque Niveau existant. Cela est essentiel car toutes les opérations concernant le Suivi des Incidents effectuées par IKAN ALM sont exécutées pendant la Phase "Suivi des Incidents". Si un Niveau n’a pas de Phase "Suivi des Incidents", aucun Incident ne sera associé aux Requêtes de niveau de ce Niveau et aucun commentaire ne sera ajouté aux Incidents!

Pour chaque Niveau existant dans le Projet, vous devez effectuer ce qui suit:

Nous ne devons exécuter cette procédure que pour les Niveaux créés avant l’association du Projet au Système de Suivi des Incidents. Les Niveaux créés après l’association au Système de Suivi des Incidents auront par défaut une Phase "Suivi des Incidents".

Modifiez le Niveau, soit à partir de l'Aperçu des Niveaux, soit à partir de la fenêtre Aperçu des Cycles de vie.
Ensuite, cliquez sur le lien Modifier les Phases en-dessous de l'Aperçu des Phases.
Ensuite, cliquez sur le lien Insérer une Phase.

La fenêtre Insérer une Phase s’affiche.

Complétez les champs pour la nouvelle Phase.

Les champs suivants sont disponibles:

Champ	Description
Phase	Sélectionnez, à partir du panneau Phases disponibles, la Phase de niveau à ajouter.
Abandon si erreur	Dans ce champ, indiquez si la Requête de niveau doit être considérée comme étant échouée si la Phase rencontre une erreur.
Insérer à la position	Ce champ indique la position dans le flux de travail du Niveau à laquelle la Phase sera insérée. La position de la Phase est également affichée dans le panneau Aperçu des Phases. Une bonne pratique consiste à insérer la Phase Suivi des Incidents avant la Phase Nettoyage Copies de travail.
Phase suivante si erreur	Ce champ indique la Phase suivante à exécuter si la Phase rencontre une erreur. Il est recommandé de sélectionner la Phase Nettoyage Copies de travail.
Libellé	Dans ce champ vous pouvez saisir un libellé pour la Phase à insérer. Si vous utilisez la même Phase plusieurs fois, il est utile d’ajouter un libellé pour donner des informations additionnelles concernant l’usage de la Phase.

Champ

Description

Phase

Sélectionnez, à partir du panneau Phases disponibles, la Phase de niveau à ajouter.

Abandon si erreur

Dans ce champ, indiquez si la Requête de niveau doit être considérée comme étant échouée si la Phase rencontre une erreur.

Insérer à la position

Ce champ indique la position dans le flux de travail du Niveau à laquelle la Phase sera insérée. La position de la Phase est également affichée dans le panneau Aperçu des Phases. Une bonne pratique consiste à insérer la Phase Suivi des Incidents avant la Phase Nettoyage Copies de travail.

Phase suivante si erreur

Ce champ indique la Phase suivante à exécuter si la Phase rencontre une erreur. Il est recommandé de sélectionner la Phase Nettoyage Copies de travail.

Libellé

Dans ce champ vous pouvez saisir un libellé pour la Phase à insérer.

Si vous utilisez la même Phase plusieurs fois, il est utile d’ajouter un libellé pour donner des informations additionnelles concernant l’usage de la Phase.

Cliquez sur le bouton Insérer pour confirmer la création de la nouvelle Phase.

Intégrer un Système de Suivi des Incidents externe

Cette section contient des informations détaillées sur l’intégration d’IKAN ALM avec un Système de Suivi des Incidents externe. Plus spécifiquement, elle décrit les tâches exécutées par la Phase "Suivi des Incidents" IKAN ALM qui est exécutée pendant une Requête de niveau.

Journal de la Phase Suivi des Incidents

Comme déjà indiqué précédemment, toutes les opérations concernant le Suivi des Incidents sont exécutées pendant la Phase "Suivi des Incidents". Les fichiers journaux générés lors de ces opérations peuvent être consultés dans l’Interface Utilisateur IKAN ALM, sur l’onglet "Journaux de Phase" de la page Informations détaillées.

Le champ "Dernier message" contient le messages de suivi des opérations exécutées par la Phase "Suivi des Incidents".

Requêtes de niveau de Construction

Une Requête de niveau de Construction est une Requête de niveau d’un Niveau de Construction. Typiquement, une Requête de niveau de Construction récupérera le dernier Code Source du RCV (Référentiel de Contrôle de Version), le construira et y ajoutera un libellé dans le RCV pour des références ultérieures.

La Phase "Suivi des Incidents" dans une Requête de niveau de Construction exécute les opérations suivantes:

analyser les messages d’enregistrement dans le RCV et trouver les références aux Incidents,
créer un lien entre les Incidents identifiés et la Requête de niveau,
synchroniser les données des Incidents associés avec les informations les plus récentes dans GitHub.

Tout d’abord, les messages sont récupérés à partir des enregistrements effectués depuis la dernière Requête de niveau réussie. Dans ces messages, les identifiants (les clés) des Incidents sont cherchés en utilisant les modèles définis dans le Système de Suivi d’incidents (les champs Modèle de recherche de Suivi d’Incident et Modèle d’Identifiant de Suivi d’Incident). La reconnaissance des correspondances ne tient pas compte de la casse.

Les doubles parmi les incidents trouvés sont retirés et ils sont associés à la Requête de niveau actuelle.

Finalement, IKAN ALM essaie de trouver la correspondance de l’Incident dans le référentiel GitHub. Si l’Incident est trouvé, la description, le statut, le propriétaire et la priorité sont récupérés à partir de GitHub, et cette information est sauvegardée dans la représentation de l’Incident dans IKAN ALM.

Requêtes de niveau pour délivrer, re-délivrer et restaurer

Si vous créez une Requête de niveau pour un Niveau de Test ou de Production, cela signifie, en termes IKAN ALM, que vous “délivrez” vers un Niveau de Test ou de Production. La “Construction active actuelle” d’un Niveau est la dernière Construction délivrée réussie sur ce Niveau.

Nous parlons d’une “Requête de niveau pour délivrer une Construction” si vous délivrez une Construction dont le numéro de construction est supérieur à celui de la Construction active actuelle sur ce Niveau.

Nous parlons d’une “Requête de niveau pour re-délivrer une Construction” si vous délivrez une Construction dont le numéro de construction est égal à celui de la Construction active actuelle sur ce Niveau.

Nous parlons d’une “Requête de niveau pour restaurer une Construction” si vous délivrez une Construction dont le numéro de construction est inférieur à celui de la Construction active actuelle sur ce Niveau.

La Phase "Suivi des Incidents" dans une Requête de niveau pour délivrer une Construction exécute les opérations suivantes:

Trouver les Incidents associés aux Requêtes de niveau de Construction exécutées depuis la dernière Requête de niveau pour délivrer une Construction
Créer un lien entre toutes ces Requêtes de niveau de Construction vers la Requête de niveau pour délivrer une Construction actuelle, en éliminant les doubles
Synchroniser les données des Incidents associés avec les informations les plus récentes dans GitHub.

En cas d’une Requête de niveau pour re-délivrer ou restaurer une Construction, il existe toujours une Requête de niveau pour délivrer une Construction précédente. Au lieu d’énumérer toutes les Requêtes de niveau de Construction, les Incidents sont copiés à partir de la Requête de niveau pour délivrer une Construction précédente, et, finalement, leurs données sont synchronisées avec l’information la plus récente disponible dans GitHub.

Il est important de comprendre que pour les Requêtes de niveau pour délivrer, re-délivrer et restaurer une Construction, les Incidents sont toujours associés en les "copiant" d’autres Requêtes de niveau, soit des Requêtes de niveau de Construction, soit d’autres Requêtes de niveau pour délivrer une Construction. Les Incidents ne sont jamais analysés sur la base des messages d’enregistrement pendant l’exécution de Requêtes de niveau pour délivrer, re-délivrer ou restaurer une Construction.

Un exemple pourrait clarifier les choses. Supposons l’ensemble de Requêtes de niveau (RN) chronologique suivant:

RN de Construction produisant la Construction 1: Incident 1 est analysé sur la base des commentaires dans le RCV
RN de Construction produisant la Construction 2: Incident 2 est analysé sur la base des commentaires dans le RCV
RN pour délivrer, délivrant la Construction 2: Incident 1 et Incident 2 sont associés (à partir des 2 Requêtes de niveau de Construction précédentes)
RN de Construction produisant la Construction 3: Incident 3 est analysé sur la base des commentaires dans le RCV
RN de Construction produisant la Construction 4: Incident 4 est analysé sur la base des commentaires dans le RCV
RN pour délivrer, délivrant la Construction 4: Incident 3 et Incident 4 sont associés (à partir des 2 Requêtes de niveau de Construction précédentes)
RN pour re-délivrer (la Construction 4): Incident 3 et Incident 4 sont associés (copiés de la Requête de niveau pour délivrer qui a délivré la Construction 4)
RN pour restaurer la Construction 2: Incident 1 et Incident 2 sont associés (copiés de la Requête de niveau pour délivrer qui a délivré la Construction 2)

Ajouter des Commentaires

Outre la récupération de l’information à partir de GitHub et l’intégration dans IKAN ALM, l’information sur les Requêtes de niveau IKAN ALM est également intégrée dans GitHub sous forme de commentaires aux Incidents GitHub. La possibilité d’ajouter des commentaires est contrôlée par le champ "Ajouter des Commentaires" dans la définition du Système de Suivi des Incidents IKAN ALM.

Actuellement, les commentaires des Incidents ne sont pas configurables et, en général, ils ressemblent à:

Comme vous pouvez le constater, le commentaire d’Incident contient un lien direct vers la Requête de niveau IKAN ALM concernée, ce qui permet aux Utilisateurs d’afficher les détails d’une Construction qui résout cet Incident.

Modification et synchronisation manuelle des Incidents

La qualité des liens créés et de la synchronisation dépend de la qualité des modèles de correspondance et de la qualité des messages d’enregistrement. Il se peut que les références d’Incident soient oubliés dans les messages d’enregistrement, que tous les identifiants d’Incident ne soient pas analysés ou que des identifiants d’Incident non valides soient analysés (faux résultats positifs). Dans ces cas, il peut être nécessaire d’ajouter, modifier, supprimer et/ou synchroniser les Incidents manuellement.

Heureusement, toutes ces fonctions sont disponibles dans l’Interface Utilisateur IKAN ALM sur l’onglet "Incidents" de la page Informations détaillées.

Pour plus d’informations, se référer au Guide de l’Utilisateur IKAN ALM.

Résolution des problèmes

En général, vous devez utiliser le bouton "Vérifier la connexion" dans la fenêtre “Modifier un Système de Suivi des Incidents”. Vérifiez les erreurs rapportées dans les champs "Message" et "Trace de la pile". Ils devraient contenir de l’information utile.

Les autres problèmes mentionnés supposent que la "vérification de la connexion" n’a pas rapporté d’erreurs.

Aucun Incident n’est associé à la Requête de niveau

Des Incidents devraient être associés à la Requête de niveau, mais l’onglet Incidents de la page Informations détaillées n’en affiche pas.

Causes possibles:

La Phase "Suivi des Incidents" n’a pas été ajoutée au Niveau pour la Requête de niveau.

Vérifiez si la Phase "Suivi des Incidents" est affichée sur la page Journaux de Phase de la fenêtre "Informations détaillées"? Si cela n’est pas le cas, modifiez les Phases du Niveau et ajoutez la Phase "Suivi des Incidents" (Associer un Système de Suivi des Incidents à un Projet).
La Phase "Suivi des Incidents" a échoué.

Vérifiez les erreurs dans le journal de la Phase "Suivi des Incidents".
La Phase "Suivi des Incidents" a réussi, mais aucun Incident n’est traité.

Vérifiez le journal. Il devrait mentionner les modèles utilisés, les balises RCV utilisées pour chercher les messages d’enregistrement (commit) et les Incidents trouvés.