GitLab Discord Kanban Bot

Bot Discord qui synchronise automatiquement les issue boards GitLab avec des salons Discord.

🚀 Fonctionnalités

• Multi-projets : Supporte plusieurs projets GitLab simultanément
• Multi-boards : Choisissez quels issue boards synchroniser par projet
• Multi-catégories : Une catégorie Discord par projet/board
• Synchronisation automatique : Crée un salon Discord pour chaque label du board GitLab
• Organisation par colonnes : Chaque salon correspond à une colonne du Kanban (To Do, In Progress, Done, etc.)
• Couleurs GitLab : Utilise les couleurs exactes des labels GitLab
• Mise à jour en temps réel : Actualise les issues périodiquement sans spam
• Interface propre : Affichage des issues sous forme d'embeds Discord élégants
• Gestion intelligente : Supprime et recrée seulement les messages modifiés
• Architecture modulaire : Code bien structuré et maintenable

📋 Prérequis

• Node.js >= 18.0.0
• Un bot Discord avec les permissions appropriées
• Un token GitLab avec accès au projet
• Une catégorie Discord dédiée

🛠️ Installation

1. Cloner le projet

   git clone <votre-repo>
   cd Kanban_BOT
   

2. Installer les dépendances

   npm install
   

3. Configuration

   cp .env.example .env
   

   Configuration de base (.env)

   Éditer le fichier .env avec vos paramètres :

   DISCORD_TOKEN=your_discord_bot_token_here
   DISCORD_GUILD_ID=your_discord_server_id_here
   
   GITLAB_URL=https://gitlab.example.com
   GITLAB_TOKEN=your_gitlab_private_token_here
   
   SYNC_INTERVAL_MINUTES=5
   LOG_LEVEL=info
   

   Configuration Multi-Projets (config/projects.json)

   Créez/modifiez le fichier config/projects.json :

   [
     {
       "name": "Mon Projet Principal",
       "projectId": "namespace/mon-projet",
       "categoryId": "1234567890123456789",
       "boardIds": [1, 2]
     },
     {
       "name": "Projet Secondaire",
       "projectId": "autre-namespace/autre-projet", 
       "categoryId": "9876543210987654321",
       "boardIds": []
     }
   ]
   

   Configuration Legacy (Un seul projet)

   Si vous préférez l'ancienne méthode, ajoutez dans .env :

   GITLAB_PROJECT_ID=your_project_id_here
   DISCORD_CATEGORY_ID=your_category_id_here
   

🚀 Utilisation

Démarrage en production

npm start

Démarrage en développement

npm run dev

📁 Structure du projet

src/
├── config/
│   └── config.js          # Configuration centralisée
├── services/
│   ├── GitLabClient.js     # Client API GitLab
│   ├── DiscordService.js   # Service Discord
│   └── SyncService.js      # Service de synchronisation
├── utils/
│   └── logger.js           # Système de logging
└── index.js                # Point d'entrée principal

⚙️ Configuration

Discord

1. Créer un bot Discord sur le Discord Developer Portal
2. Permissions requises :
   • Manage Channels
   • Send Messages
   • Embed Links
   • Read Message History
3. Inviter le bot sur votre serveur avec ces permissions

GitLab

1. Créer un token d'accès personnel dans GitLab
2. Permissions requises :
   • read_api
   • read_repository
3. Récupérer l'ID du projet depuis l'URL ou les paramètres du projet

Catégorie Discord

1. Créer une catégorie dédiée sur votre serveur Discord
2. Récupérer l'ID de la catégorie (mode développeur requis)

🔄 Fonctionnement

1. Au démarrage : Le bot lit la configuration multi-projets
2. Initialisation : Pour chaque projet configuré :
   • Connexion à GitLab et récupération des boards
   • Filtrage des boards selon boardIds (si spécifié)
   • Suppression des salons existants dans la catégorie Discord
3. Création des salons : Un salon par label/colonne de chaque board
4. Synchronisation des issues : Les issues sont affichées dans le salon correspondant
5. Mise à jour périodique : Actualisation automatique de tous les projets

Architecture Multi-Projets

Projet 1 (Catégorie Discord A)
├── Board "Kanban" 
│   ├── Salon "kanban-to-do" = Issues avec label "To Do"
│   ├── Salon "kanban-doing" = Issues avec label "Doing"
│   └── Salon "kanban-done" = Issues avec label "Done"
└── Board "Bugs"
    ├── Salon "bugs-open" = Issues avec label "Open"
    └── Salon "bugs-fixed" = Issues avec label "Fixed"

Projet 2 (Catégorie Discord B)
└── Board "Features"
    ├── Salon "features-backlog" = Issues avec label "Backlog"
    └── Salon "features-dev" = Issues avec label "Development"

Configuration des Boards

• boardIds: [] : Synchronise TOUS les boards du projet
• boardIds: [1, 2] : Synchronise seulement les boards avec les IDs 1 et 2
• Noms des salons : Format {board-name}-{label-name} (ex: "kanban-to-do")

📊 Logs et monitoring

Le bot utilise un système de logging configurable :

• error : Erreurs critiques uniquement
• warn : Avertissements et erreurs
• info : Informations générales (par défaut)
• debug : Informations détaillées pour le débogage

🛡️ Gestion des erreurs

• Reconnexion automatique Discord en cas de déconnexion
• Retry automatique pour les appels API GitLab
• Logs détaillés pour faciliter le débogage
• Arrêt propre avec gestion des signaux système

🔮 Fonctionnalités futures

• Déplacement d'issues entre labels via Discord
• Commandes Discord pour contrôler le bot
• Support de plusieurs projets GitLab
• Notifications en temps réel via webhooks
• Interface web de configuration

🤝 Contribution

1. Fork le projet
2. Créer une branche feature (git checkout -b feature/AmazingFeature)
3. Commit les changements (git commit -m 'Add some AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

📝 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🆘 Support

En cas de problème :

1. Vérifier les logs du bot
2. Valider la configuration dans .env
3. Tester les permissions Discord et GitLab
4. Ouvrir une issue sur GitHub avec les logs d'erreur