La gemme gitlab-triage : votre alliée pour des workflows Agile automatisés

Bienvenue dans notre série d'articles de blog baptisée « Premiers pas avec GitLab », dans laquelle nous aidons les nouveaux utilisateurs à se familiariser avec la plateforme DevSecOps de GitLab.

Découvrez dans cet article une alliée précieuse pour automatiser vos workflows Agile : la gemme gitlab-triage. Finies les tâches manuelles fastidieuses, place à une productivité maximale et à des processus simplifiés !

Pourquoi automatiser votre workflow ?

Dans le domaine du développement logiciel, la productivité est la clé du succès. En automatisant des tâches répétitives telles que le classement des tickets et des merge requests par ordre de priorité, votre équipe peut se concentrer sur sa mission première : concevoir des logiciels robustes et innovants.

Avec la gemme gitlab-triage, vous pouvez :

• Assurer la cohérence : appliquez des labels et attribuez des tickets automatiquement en fonction de règles prédéfinies.
• Améliorer les temps de réponse : obtenez des retours immédiats et traitez rapidement les nouveaux tickets et merge requests.
• Éliminer les tâches manuelles : triez, classez, priorisez, mettez à jour les tickets sans intervention humaine.
• Stimuler la productivité : offrez à votre équipe plus de temps pour coder, innover et se concentrer sur des tâches à forte valeur ajoutée.

Qu'est-ce que la gemme gitlab-triage ?

La gemme gitlab-triage est une bibliothèque Ruby qui vous permet de créer des bots capables d'interagir intelligemment avec vos projets GitLab et qui peuvent effectuer automatiquement un large éventail d'actions, notamment :

• Ajout de labels : classez automatiquement vos tickets et vos merge requests.
• Commentaires automatisés : fournissez des retours, posez des questions ou partagez des informations clés.
• Attribution intelligente : attribuez les tickets et les merge requests aux membres appropriés de votre équipe, selon des critères définis.
• Fermeture automatique : clôturez les tickets et merge requests obsolètes ou résolus.
• Création conditionnelle : générez de nouveaux tickets en fonction d'événements ou de conditions spécifiques.
• Et bien plus encore !

Pour en savoir plus, consultez le dépôt de la gemme gitlab-triage.

Configuration de votre bot de classement

Prêt à mettre en place votre premier bot de tri automatisé ? Suivez le guide !

1. Installez la gemme. Remarque : assurez-vous que Ruby est installé sur votre machine, puis exécutez la commande gem suivante :

gem install gitlab-triage

2. Récupérez votre token d'API GitLab.

• Accédez aux paramètres de votre profil GitLab.
• Cliquez sur Jetons d'accès.
• Créez un nouveau jeton d’accès avec la portée api.
• Conservez-le en lieu sûr et définissez sa date d'expiration selon la durée de ce tutoriel.

3. Définissez vos stratégies de classement.

Créez un fichier nommé .triage-policies.yml dans le répertoire racine de votre projet. Il contiendra les règles qui régissent le comportement de votre bot. Voici un exemple simple :

---
- name: "Apply 'WIP' label"
  condition:
    draft: true
  action:
    labels:
      - status::wip

- name: "Request more information on old issue"
  condition:
   date:
    attribute: updated_at
    condition: older_than
    interval_type: months
    interval: 12
  action:
    comment: |
      {{author}} This issue has been open for more than 12 months, is this still an issue?

Cette configuration définit deux stratégies :

• La première applique automatiquement le label status::wip à tout ticket enregistré en tant que brouillon.
• La deuxième ajoute un commentaire à tout ticket qui n'a pas été mis à jour depuis 12 mois.

4. Exécutez votre bot.

Vous pouvez exécuter votre bot manuellement à l'aide de la commande suivante :

gitlab-triage -t <your_api_token> -p <your_project_id>

Remplacez <your_api_token> par votre token d'API GitLab et <your_project_id> par l'ID de votre projet GitLab. Pour effectuer un test sans appliquer les actions (mode simulation), ajoutez l’option -n ou --dry-run.

Automatisation avec GitLab CI/CD

Pour aller plus loin, vous pouvez intégrer l’exécution de votre bot directement dans vos pipelines GitLab CI/CD. Voici un exemple de configuration .gitlab-ci.yml :

triage:
  script:
    - gem install gitlab-triage
    - gitlab-triage -t $GITLAB_TOKEN -p $CI_PROJECT_ID
  only:
    - schedules

Cette configuration définit un job nommé « triage » qui installe la gemme gitlab-triage et exécute le bot à l'aide de deux variables CI/CD prédéfinis : $GITLAB_TOKEN et $CI_PROJECT_ID. La clause only: schedules garantit que ce job s'exécute uniquement selon un calendrier défini.

Pour automatiser l’exécution de votre bot à intervalles réguliers, accédez aux paramètres CI/CD de votre projet GitLab, puis à l'onglet Calendriers. Créez un calendrier de planification et définissez la fréquence d'exécution de votre bot (par exemple, quotidiennement, toutes les heures).

Stratégies de classement avancées

La gemme gitlab-triage offre un large éventail de fonctionnalités avancées pour créer des stratégies de classement plus complexes :

• Expressions régulières : pour des correspondances plus puissantes dans vos stratégies.
• Stratégies de synthèse : pour regrouper des tickets associés en un ticket unique récapitulatif.
• Actions personnalisées : pour effectuer des opérations plus complexes à l'aide de l'API GitLab, en utilisant des blocs de code Ruby.

Voici deux exemples concrets utilisés par l'équipe Developer Advocacy de GitLab. Vous pouvez consulter l'intégralité des stratégies dans ce fichier.

- name: Issues where DA team member is an assignee outside DA-Meta project i.e. DevRel-Influenced
  conditions:
    assignee_member:
      source: group
      condition: member_of
      source_id: 1008
    state: opened
    ruby: get_project_id != 18 
    forbidden_labels:
      - developer-advocacy
  actions:   
    labels:
      - developer-advocacy
      - DevRel-Influenced
      - DA-Bot::Skip

Cet exemple concerne les tickets d'un groupe, à l'exclusion de ceux appartenant au projet portant l'ID 18. Il montre des tickets assignés à des membres du groupe portant l'ID 1008 et qui n'incluent pas le label developer-advocacy. Cette stratégie permet à l'équipe Developer Advocacy de GitLab d'identifier les tickets attribués à ses membres, sur lesquels ils ont contribué mais pour un autre projet, et de suivre facilement ces contributions en y ajoutant automatiquement le label de l'équipe pour une vision claire de l'impact transversal de ses membres.

- name: Missing Due Dates
  conditions:
    ruby: missing_due_date
    state: opened
    labels:
      - developer-advocacy
    forbidden_labels:
      - DA-Due::N/A
      - DA-Bot::Skip
      - DA-Status::FYI
      - DA-Status::OnHold
      - CFP
      - DA-Bot::Triage
  actions:
    labels:
      - DA-Bot-Auto-Due-Date
    comment: |
      /due #{get_current_quarter_last_date}

Ce deuxième exemple permet de trier tous les tickets portant le label developer-advocacy, qui n'incluent aucun label figurant dans la liste des labels interdits, et dont la date d'échéance est dépassée. Cette stratégie de classement met automatiquement à jour la date d'échéance en ajoutant un commentaire au ticket avec une commande slash et d'une nouvelle date générée dynamiquement à l'aide de Ruby.

Les scripts Ruby utilisés dans ces stratégies sont définis dans un fichier séparé, comme illustré ci-dessous. Cette approche offre une grande souplesse dans la création de filtres et d’actions personnalisés. Vous pouvez notamment voir des fonctions dédiées aux différentes commandes Ruby que nous avons utilisées dans nos stratégies de classement.

require 'json'
require 'date'
require "faraday"
require 'dotenv/load'

module DATriagePlugin
  def last_comment_at
    conn = Faraday.new(
      url: notes_url+"?sort=desc&order_by=created_at&pagination=keyset&per_page=1",
      headers: {'PRIVATE-TOKEN' => ENV.fetch("PRIV_KEY"), 'Content-Type' => 'application/json' }
    )

    response = conn.get()
    if response.status == 200
      jsonData = JSON.parse(response.body)
      if jsonData.length > 0
        Date.parse(jsonData[0]['created_at'])
      else
        Date.parse(resource[:created_at])
      end
    else
      Date.parse(resource[:created_at])
    end
  end

  def notes_url
    resource[:_links][:notes]
  end

  def get_project_id
    resource[:project_id]
  end

  def get_current_quarter_last_date()
    yr = Time.now.year
    case Time.now.month
    when 2..4
      lm = 4
    when 5..7
      lm = 7
    when 8..10
      lm = 10
    when 11..12
      lm = 1
      yr = yr + 1
    else
      lm = 1    
    end

    return Date.new(yr, lm, -1) 
  end

  def one_week_to_due_date
    if(resource[:due_date] == nil)
      false
    else
      days_to_due = (Date.parse(resource[:due_date]) - Date.today).to_i
      if(days_to_due > 0 && days_to_due < 7)
        true
      else
        false
      end
    end
  end

  def due_date_past
    if(resource[:due_date] == nil)
      false
    else
      Date.today > Date.parse(resource[:due_date])
    end
  end

  def missing_due_date
    if(resource[:due_date] == nil)
      true
    else
      false
    end
  end

end

Gitlab::Triage::Resource::Context.include DATriagePlugin

Le bot de classement par ordre de priorité est exécuté à l'aide de la commande suivante :

`gitlab-triage -r ./triage_bot/issue_triage_plugin.rb --debug --token $PRIV_KEY --source-id gitlab-com --source groups`  

• -r : transmet un fichier de prérequis pour le classement par ordre de priorité en cours. Dans le cas présent, il s’agit d’un fichier contenant des fonctions Ruby personnalisées.
• --debug : affiche les informations de débogage en sortie.
• --token : permet de transmettre un token d'API GitLab valide.
• --source : spécifie si les tickets à analyser se trouvent dans un groupe ou un projet.
• --source-id : reçoit l'ID du type de source sélectionné. Dans le cas présent, celui du groupe ciblé.

Dans le projet GitLab triage-ops, autre exemple concret plus complexe, vous apprendrez à créer votre propre bot de classement par ordre de priorité à grande échelle.

Bonnes pratiques

• Commencez par les bases : utilisez des stratégies simples et augmentez progressivement leur complexité.
• Testez minutieusement : testez vos stratégies dans un environnement de préproduction avant de les déployer en production.
• Surveillez régulièrement : surveillez l'activité de votre bot pour vous assurer qu'il se comporte comme prévu.
• Nommez clairement vos stratégies : attribuez à vos stratégies des noms clairs et descriptifs pour faciliter leur maintenance.
• Définissez attentivement la portée de vos filtres : évitez de filtrer les tickets dans des groupes incluant des milliers de tickets, car cela pourrait ralentir le processus de classement par ordre de priorité, voire le faire échouer en raison des limites de débit de l'API GitLab.
• Priorisez l'utilisation de labels pour le classement : pour éviter de spammer les autres utilisateurs avec des commentaires et des tickets, les labels sont un moyen efficace d'effectuer un classement par ordre de priorité, clair, propre, non intrusif.

Prenez le contrôle de votre workflow

Avec la gemme gitlab-triage, vous pouvez automatiser votre workflow GitLab et améliorer la productivité de vos équipes. Commencez par créer des bots de classement simples, puis explorez progressivement les fonctionnalités plus avancées. Vous serez surpris du temps et de l’énergie que vous pouvez économiser !

Découvrez les autres articles de cette série « Premiers pas avec GitLab » :

• Comment gérer les utilisateurs

• Comment importer vos projets dans GitLab

• Comment maîtriser la gestion de projet