212 lines
6.3 KiB
Markdown
212 lines
6.3 KiB
Markdown
# 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**
|
|
```bash
|
|
git clone <votre-repo>
|
|
cd Kanban_BOT
|
|
```
|
|
|
|
2. **Installer les dépendances**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Configuration**
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
### Configuration de base (.env)
|
|
Éditer le fichier `.env` avec vos paramètres :
|
|
```env
|
|
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` :
|
|
```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` :
|
|
```env
|
|
GITLAB_PROJECT_ID=your_project_id_here
|
|
DISCORD_CATEGORY_ID=your_category_id_here
|
|
```
|
|
|
|
## 🚀 Utilisation
|
|
|
|
### Démarrage en production
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
### Démarrage en développement
|
|
```bash
|
|
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](https://discord.com/developers/applications)
|
|
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
|