Discord

L'intégration Discord connecte votre serveur Discord à Almirant afin d'exécuter des commandes d'agents, de recevoir des notifications d'événements du projet et de contrôler des sessions de travail directement depuis le chat.

Fonctionnement

Almirant s'intègre à Discord par l'intermédiaire d'un bot qui utilise OAuth2 pour se connecter à votre serveur. Le bot peut :

• Exécuter des slash commands -- Des commandes telles que /implement et /plan pour lancer des travaux d'agent depuis Discord.
• Envoyer des notifications -- Almirant notifie via Discord des événements pertinents (work items, sprints, PRs, CI/CD).
• Contrôler les sessions -- Des boutons interactifs pour arrêter, mettre en pause ou répondre aux questions des agents.
• Créer des threads automatiques -- Chaque travail d'agent crée un thread dédié pour suivre sa progression.

Configurer l'intégration Discord

1. Se connecter via OAuth

Contrairement aux autres bots, Discord utilise OAuth2 pour une connexion sécurisée :

1. Accédez à Configuration > Intégrations > Discord.
2. Cliquez sur Connecter Discord.
3. Discord vous demandera de sélectionner un serveur sur lequel vous disposez de permissions d'administrateur.
4. Autorisez les permissions demandées (envoyer des messages, créer des threads, utiliser des slash commands).
5. Almirant enregistrera automatiquement les slash commands sur votre serveur.

2. Configurer le canal par défaut

Après la connexion :

1. Accédez à Configuration > Intégrations > Discord.
2. Sélectionnez le canal par défaut auquel le bot enverra les notifications.
3. Enregistrez la configuration.

3. Vérifier la connexion

1. Dans la configuration Discord, cliquez sur Envoyer un message de test.
2. Vérifiez que le message apparaît dans le canal sélectionné.

Slash commands

Le bot Discord prend en charge des slash commands pour interagir avec Almirant :

Commande	Description
/implement [work_item_id]	Lance un travail d'implémentation pour le work item spécifié
/plan [work_item_id]	Lance un travail de planification pour le work item spécifié
/status	Affiche les travaux actifs (queued, running, waiting_for_input)
/status [job_id]	Affiche l'état détaillé d'un travail spécifié

Options des commandes

Les commandes /implement et /plan acceptent des options supplémentaires :

Option	Description
work_item_id	(Obligatoire) L'ID du work item (par ex. : A-123)
provider	(Facultatif) Le fournisseur d'agent : claude-code, codex ou zipu

Exemple d'utilisation

/implement work_item_id:A-1189
/implement work_item_id:A-1189 provider:claude-code
/plan work_item_id:A-1190
/status job_id:abc123-def456

Threads automatiques

Lorsque vous exécutez une slash command, le bot crée automatiquement un thread privé pour ce travail :

• Le nom du thread indique le type de travail et le task ID
• Tous les messages de progression de l'agent sont envoyés dans le thread
• Les boutons de contrôle (Stop, Shutdown) apparaissent dans le thread
• Le thread est automatiquement archivé après 24 heures d'inactivité

Boutons interactifs

Pendant l'exécution d'un travail, le bot affiche des boutons pour contrôler la session :

Bouton	Action
Stop	Arrête le travail actuel tout en conservant son état
Shutdown	Arrête complètement le travail et ferme la session

Lorsque l'agent a une question, des options apparaissent sous forme de boutons ou de menu de sélection. Sélectionnez l'option souhaitée pour répondre.

Notifications

Configurez les événements du projet que vous souhaitez recevoir comme notifications dans Discord :

Événement	Description
Work item créé	Un nouveau work item est créé
Work item déplacé	Un work item change de colonne dans le board
Work item attribué	Un work item est attribué à quelqu'un
Work item terminé	Un work item est marqué comme done
Sprint démarré/fermé	Un sprint commence ou se termine
Milestone terminé	Un milestone est terminé
PR ouvert/merged	Un pull request est ouvert ou merged
CI échouée	Une build CI échoue
Travail d'agent terminé/échoué	Un travail d'agent se termine

Pour configurer les notifications :

1. Accédez à Configuration > Intégrations > Discord.
2. Cliquez sur Configurer les notifications.
3. Activez ou désactivez les événements souhaités.
4. Enregistrez les modifications.

Lier des projets à des canaux

Vous pouvez configurer des canaux spécifiques pour différents projets :

1. Accédez à la configuration du projet.
2. Dans la section Discord, sélectionnez le canal de destination.
3. Les notifications et les threads de ce projet seront envoyés au canal configuré.

S'il n'existe aucun canal spécifique, le canal par défaut de l'organisation est utilisé.

Déconnecter Discord

Pour déconnecter le bot :

1. Accédez à Configuration > Intégrations > Discord.
2. Cliquez sur Déconnecter.
3. Confirmez la déconnexion.

attention

Déconnecter le bot arrêtera les slash commands et les notifications via Discord. Les travaux en cours ne seront pas annulés automatiquement.

Pour les développeurs

Architecture de l'intégration

L'intégration Discord se compose de deux routes principales :

• OAuth routes (/api/integrations/discord) : Gère le flux OAuth2, la gestion des connexions, des canaux et des préférences de notification.
• Interactions webhook (/webhooks/discord/interactions) : Reçoit et traite les slash commands, les boutons et les menus de sélection.

Flux OAuth

Usuario --> GET /authorize --> Discord OAuth --> GET /callback
                                                      |
                                    +------------ Token exchange
                                    |
                            Create connection + Register slash commands

Flux d'interactions

Discord --> POST /webhooks/discord/interactions --> Verify signature
                                                         |
                              +--------------------------+
                              |           |              |
                            PING     Command        Component
                              |           |              |
                           PONG    Queue job      Process action

Slash commands enregistrées

Les commandes sont automatiquement enregistrées dans le guild pendant OAuth :

• implement : Lance un travail d'implémentation
• plan : Lance un travail de planification
• status : Consulte l'état des travaux

Vérification de signature

Toutes les interactions sont vérifiées avec Ed25519 et la clé publique Discord (DISCORD_PUBLIC_KEY). Cela garantit que les requests proviennent de Discord.

Variables d'environnement

Variable	Description
DISCORD_CLIENT_ID	ID de l'application Discord
DISCORD_CLIENT_SECRET	Secret de l'application
DISCORD_PUBLIC_KEY	Clé publique servant à vérifier les signatures
DISCORD_BOT_TOKEN	Token du bot pour envoyer des messages
DISCORD_APPLICATION_ID	ID de l'application (pour les slash commands)
DISCORD_OAUTH_REDIRECT_URI	URI de callback OAuth