Intégrations
Les intégrations relient un board Stib à une source de travail externe. Une connexion appartient soit au serveur, où tous les projets la partagent, soit à un seul projet, où elle est visible et utilisable uniquement là. Créez la connexion à la bonne portée, puis attachez-la avec son mapping au board concerné.
Fournisseurs
La couche actuelle comprend :
| Fournisseur | Source |
|---|---|
| GitHub | Issues et pull requests |
| Azure DevOps | Work items |
| Jira | Issues et epics |
| Linear | Issues et projets |
| Plane | Issues, par workspace, avec jetons personnels |
| BMAD | Artefacts BMAD locaux, sans identifiant distant |
| Personnalisé | API REST décrite manuellement ou importée depuis OpenAPI |
La disponibilité peut dépendre du plan de licence et de la configuration serveur. La règle de plan par fournisseur est la même quelle que soit la portée de la connexion ; après une rétrogradation, l’interrogation en arrière-plan s’arrête pour les fournisseurs que le plan ne couvre plus.
Parcours de configuration
Connexion serveur
Partagée par tous les projets ; exige des droits d’administration serveur.
- Ouvrez Paramètres → Serveur → Intégrations et créez une connexion.
- Saisissez endpoint/compte et l’identifiant le plus limité possible.
- Testez la connexion.
Une connexion serveur n’épingle pas de cible distante : chaque board qui s’y attache choisit la sienne.
Connexion de projet
Propre à un projet et invisible des autres ; exige un admin du projet (propriétaire ou admin du projet, admin de l’organisation ou admin global). Ses événements sont consignés dans l’Historique du projet.
- Ouvrez Paramètres du projet → Intégrations et créez une connexion. Les connexions serveur y figurent aussi, en lecture seule, sous Connexions serveur ; elles se configurent dans les paramètres serveur.
- Saisissez endpoint/compte et identifiant, puis testez la connexion, comme pour une connexion serveur.
- Choisissez la cible distante (dépôt, projet, équipe, workspace, filtre selon le fournisseur). Elle est épinglée sur la connexion. BMAD travaille sur des artefacts locaux et saute cette étape.
Changer ensuite la cible épinglée n’affecte que les boards attachés après : un board déjà attaché conserve la cible avec laquelle il l’a été, puisque ses cartes importées référencent les éléments de ce conteneur. Pour déplacer un board existant, détachez-le puis rattachez-le.
Attachement d’un board
- Ouvrez les paramètres d’intégration du board cible et choisissez une connexion.
- Avec une connexion serveur, choisissez le conteneur externe (dépôt, projet, workspace…). Avec une connexion de projet, le board hérite de la cible épinglée, affichée en lecture seule, et cette étape disparaît.
- Mappez états/champs externes vers colonnes et champs Stib.
- Choisissez import manuel ou automatique puis prévisualisez avant la synchronisation.
Une définition d’intégration peut exister sans être attachée à tous les boards.
Les trois axes d’un mapping de colonne
Chaque colonne mappée porte trois réglages indépendants. Les confondre est la cause habituelle du « il ne se passe rien » :
| Axe | Valeurs | La question à laquelle il répond |
|---|---|---|
| Import | Aucun / Manuel / Auto | un item du fournisseur devient-il une carte ? |
| Export | Aucun / Manuel / Auto | une carte née ici devient-elle un item ? |
| Sync | Aucun / Entrant / Sortant / Bidirectionnel | une carte déjà appariée suit-elle, et dans quel sens ? |
Les deux premiers décident d’une naissance, le troisième d’un suivi, et aucun ne se déduit des autres. Une colonne peut légitimement créer dans les deux sens tout en ne propageant les déplacements que vers le fournisseur — sens unique sur les déplacements, deux sens sur la création.
L’export vaut Aucun par défaut : un board existant garde donc exactement le comportement qu’il avait. Réglé sur Auto, toute carte créée dans cette colonne ouvre un item chez le fournisseur ; réglé sur Manuel, le menu de la carte propose Créer chez le fournisseur à la place. Auto conserve cette entrée de menu : c’est le rattrapage d’une carte dont la création a échoué, ou d’une carte antérieure au réglage.
Une fois la carte et l’item appariés — que la carte vienne d’un import ou d’un export — l’axe Sync régit tout le reste : déplacements, titre, description, labels, priorité.
Tous les fournisseurs ne savent pas créer. BMAD ne le fait jamais, et un fournisseur REST personnalisé ne le fait qu’une fois son endpoint de création configuré. Un fournisseur qui ne sait pas créer ignore simplement le réglage.
Statuts reçus et statut envoyé
Une colonne reçoit autant de statuts du fournisseur qu'on veut et en envoie au plus un. Quand un item atteint un statut que la colonne reçoit, sa carte y entre (si la sync de la colonne est Entrante ou Bidirectionnelle), et l'import propose les items de tous ces statuts. Poser une carte dans la colonne écrit le statut qu'elle envoie, et un item créé depuis la colonne naît à ce statut.
Un statut n'est reçu que par une colonne — sinon rien ne dirait où poser la carte — mais plusieurs colonnes peuvent envoyer le même. Un ticket terminé peut donc arriver dans votre dernière colonne alors qu'elle continue d'écrire son propre statut : faites recevoir à « Livrée » Livrée, Clôturée et Validée en production, et envoyer Livrée.
Suivre les déplacements entrants ou importer automatiquement demande un statut reçu ; pousser les déplacements ou créer des items demande un statut envoyé. Sinon l'enregistrement est refusé, avec la raison sous la ligne.
Statuts sans colonne, sous le tableau du mapping, liste les statuts du fournisseur portés par des cartes du board qu'aucune colonne ne reçoit ni n'envoie, avec le nombre de cartes et leur colonne. Ces cartes restent où elles sont ; donnez le statut à une colonne pour les ranger.
Une carte déplacée à la main attend que le fournisseur renvoie le statut envoyé. D'ici là — quelques minutes au plus — un statut plus ancien revenu d'une synchro ou d'un webhook ne ramène pas la carte.
Import et synchronisation
Les cartes importées conservent identifiant et lien externes. Stib suit la synchronisation et signale conflits ou opérations non prises en charge. Décidez quelle source fait autorité pour chaque champ ; un flux bidirectionnel ambigu peut osciller ou écraser l’intention de l’utilisateur.
Les webhooks accélèrent les mises à jour entrantes ; une synchro planifiée/manuelle réconcilie les événements manqués. Les modifications sortantes dépendent des capacités et mappings du fournisseur.
Fournisseurs REST personnalisés
Un fournisseur personnalisé définit URL de base, authentification, endpoints, pagination, formes liste/détail, chemins de champs et mappings d’état. Créer des items en sortie demande un endpoint de plus : une URL de création, sa méthode, et un gabarit de corps où porte une variable configurée et {title} / {description} / {status} portent la carte. La réponse est relue par les mêmes mappings de champs que l’endpoint de détail : elle doit donc renvoyer l’item créé, dont Stib a besoin de l’identifiant pour apparier la carte. L’authentification peut utiliser clé API en en-tête, Basic, en-têtes/paramètres explicites et une option Bearer présentée sous forme OAuth. Cette dernière envoie actuellement le secret client enregistré directement comme jeton Bearer ; Stib n’effectue pas encore un échange complet de jeton OAuth 2.0 pour les fournisseurs personnalisés.
Utilisez test et prévisualisation contre des endpoints non destructifs. Une description OpenAPI importée n’est qu’un point de départ : vérifiez opération, pagination et champs manuellement.
Sécurité réseau
Stib bloque par défaut les cibles loopback/privées pour réduire le risque SSRF. STIB_ALLOW_PRIVATE_URLS=1 élargit l’accès pour un déploiement LAN volontaire et ne doit pas être activé sur un serveur multi-tenant ou exposé sans contrôles réseau supplémentaires. Cette variable ne concerne que les connexions serveur : une connexion de projet reste toujours sur des hôtes publics, quoi que dise l’environnement, car un admin de projet n’a jamais fait ce choix de déploiement.
Stockez les secrets dans le formulaire, pas dans les templates de mapping. Seul un administrateur serveur enregistre un secret sur une connexion serveur ; sur une connexion de projet, seul un admin du projet peut la créer, la modifier, la supprimer, la tester ou l’introspecter. Éditeurs et contributeurs attachent des boards et parcourent projets et statuts distants ; les lecteurs ne font que la voir dans la liste. Les en-têtes personnalisés sont chiffrés et leurs valeurs enregistrées restent cachées. Faites la rotation via le flux d’édition puis retestez.
Dépannage
Vérifiez test de connexion, état, mapping du board, logs serveur, audit, permissions/quotas fournisseur, livraison webhook et vue DNS/réseau du serveur. Une URL joignable depuis le client bureau peut ne pas l’être depuis le conteneur serveur.
Suite : Pipeline et automatisation et Audit et collaboration.