Créez un système de migration des rapports de bug de GitHub à votre GitLab – Partie 2/2

2. Découverte de l’API GitLab

La documentation de l’API GitLab est bien évidemment disponible sur le Web (https://docs.gitlab.com/ee/api/README.html#gitlab-api). Montrons ici quelques cas d’utilisation, en utilisant l’instance GitLab hébergée par Framasoft (https://framagit.org/).

2.1 Authentification

Comme pour l’API GitHub, il est nécessaire de savoir s’authentifier.

2.1.1 Par pseudo/mot de passe

Sur GitLab, l’authentification par pseudo/mot de passe permet uniquement de récupérer un jeton privé (également disponible dans l’interface web) :

Voyons maintenant comment utiliser ce jeton privé.

2.1.2 Jeton privé

Le jeton privé que nous venons de récupérer peut maintenant être utilisé pour interroger l’API, par exemple afin de lister nos projets :

2.1.3 OAuth2

Il est également possible d’utiliser OAuth2 afin de bénéficier d’une gestion plus fine des permissions. Une documentation complète est disponible sur le Web (https://docs.gitlab.com/ee/api/README.html#oauth-2-tokens), mais voyons tout de même rapidement les étapes nécessaires à l’obtention d’un jeton.

Il faut tout d’abord créer une application en passant par l’interface web de GitLab (voir figure 2).

Fig. 2 : Création d’une application dans GitLab.


GitLab affichera alors votre
Application ID, votre secret ainsi que l’URL de redirection que vous avez indiquée. Utilisez ces informations pour construire l’URL suivante :

Dégainez votre butineur et rendez-vous sur cette page, donnez à l’application les permissions qu’elle vous demande, et vous serez redirigé vers une page dont l’URL se terminera par code=$CODE. Une requête vous permettra d’obtenir (enfin !) votre jeton OAuth2 :

Vous pouvez ensuite utiliser ce jeton dans vos requêtes :

2.2 Une bibliothèque : python-gitlab

Rendons-nous la vie plus simple en utilisant une bibliothèque Python : python-gitlab en version 0.20. S’authentifier en utilisant un jeton privé se fait très simplement :

Il est ensuite possible d’explorer la bibliothèque comme nous l’avons fait avec PyGithub :

Voyons dans la prochaine partie comment utiliser python-gitlab pour manipuler nos projets.

3. Exemple : migrations des rapports de bugs

Lorsqu’un utilisateur de GitLab veut créer un nouveau projet, il a la possibilité d’importer un projet existant depuis un autre site, notamment GitHub (voir figure 3). Le dépôt Git sera automatiquement importé, et les rapports de bugs seront copiés. Comment pourrions-nous utiliser les API de GitHub et de GitLab afin d’implémenter une fonctionnalité similaire ?

Fig. 3 : GitLab permet d’importer un projet depuis un autre service.

3.1 Idée générale

L’idée de base est très simple : il suffit en effet de créer un nouveau projet, puis de migrer chacun des services associés (bugs, wiki, etc.) de GitHub vers GitLab. Nous nous contenterons ici de migrer les bugs. Regardons le point d’entrée de notre code :

Pour l’instant, tout est facilement compréhensible. On notera bien évidemment que gl fait référence à GitLab, et gh à GitHub. Il ne nous reste plus qu’à regarder dans le détail comment définir les fonctions que nous venons d’introduire.

3.2 Créer un nouveau projet

Cette étape est sans la plus facile : elle consiste en un seul appel à l’API GitLab, et ne nécessite qu’un seul paramètre, le nom du projet :

Après avoir exécuté cette fonction, un nouveau projet apparaît dans notre tableau de bord GitLab.

3.3 Créer les rapports de bugs

Dans la fonction migrate_gh_project, nous itérons sur les rapports de bugs afin de les cloner un par un. Idéalement, nous aimerions conserver cinq informations :

  • le titre du rapport ;
  • la description du bug ;
  • la date de création du bug ;
  • l’auteur du bug ;
  • les commentaires.

Comme nous pouvons le voir dans le code de la fonction gitlab_clone_github_issue, les trois premières informations peuvent être passées à gl_project.issues.create. Spécifier l’auteur du bug est plus difficile :

  • il a peut-être un compte sur GitHub, mais pas sur votre instance GitLab ;
  • un problème de permissions se pose : un utilisateur ne peut pas créer un bug en usurpant l’identité d’un autre.

Nous choisissons ici d’inclure le nom de l’auteur dans la description (c’est l’approche implémentée par l’outil officiel de migration fourni par GitLab).

Il ne nous reste plus qu’à cloner les commentaires.

3.4 Créer les commentaires

Créer un commentaire est une opération relativement similaire à la création d’un rapport de bug. Nous rencontrons le même problème concernant les auteurs des commentaires, que nous contournons de la même façon que précédemment :

Nous avons maintenant toutes les pièces du puzzle ! Si l’on exécute la fonction migrate_gh_project avec un nom de projet existant sur notre compte, un projet similaire apparaîtra dans GitLab, avec les bugs reproduits (presque) à l’identique.

3.5 Améliorations possibles

Bien entendu, ce code n’est qu’un simple exemple de l’utilisation combinée des API de GitHub et GitLab. Nous pourrions y apporter de nombreuses améliorations :

  • seuls les bugs sont migré (même le code du dépôt est absent de notre nouveau projet), il conviendrait de tout copier ;
  • seuls les bugs ouverts sont copiés (get_issues ne retourne par défaut que ceux-ci), il faudrait également copier ceux qui ont été résolus ;
  • la visibilité du projet est « privée » par défaut, mais nous pourrions corriger cela en modifiant gitlab_create_project ; 
  • afin de pouvoir migrer nos projets de n’importe quel service en ligne vers n’importe quel autre, il faudrait donner à notre code une meilleure architecture.

Tout ceci est possible grâce aux deux bibliothèques que nous avons utilisées jusqu’ici.

Conclusion

Nous avons montré à quel point il était facile d’utiliser les API de GitHub et GitLab grâce à des bibliothèques Python, et avons réussi à construire une application certes rudimentaire, mais tout à fait fonctionnelle, qui nous a permis de nous authentifier, de lire des données et d’en créer d’autres.

De nombreuses API fonctionnent de façon similaire, en proposant diverses méthodes d’authentification (par mot de passe, avec des jetons, avec OAuth2, etc.) et en permettant à l’utilisateur de récupérer et de modifier l’état du système. La plupart d’entre elles sont également utilisables au travers de bibliothèques Python tout aussi simples d’accès que celles dont il était question dans cet article. La méthodologie employée ici (exploration de l’API avec curl, authentification, découverte de la bibliothèque dans l’interpréteur Python…) aura donc sans doute l’occasion d’être réutilisée.

Cyril ROELANDT

Retrouvez cet article (et bien d’autres) dans GNU/Linux Magazine Hors-Série n°90, disponible sur la boutique et sur la plateforme de lecture en ligne Connect !

Laisser un commentaire