Dépannage

Quand quelque chose coince entre l’agent, CodBoard et votre dépôt, commencez ici. Chaque cas donne le symptôme, la cause probable, une commande de diagnostic, la correction et le résultat attendu.

Clé API absente ou invalide

• Symptôme — les appels d’outils échouent avec 401 · Invalid or missing API key (API) ou Missing CodBoard API key (x-api-key header) (serveur MCP).
• Cause probable — CODBOARD_API_KEY n’est pas exportée dans l’environnement de l’agent, a été révoquée, ou le header envoyé n’est pas x-api-key.
• Diagnostic — vérifiez que la variable est présente (printenv CODBOARD_API_KEY) et qu’elle commence par codboard_sk_.
• Correction — régénérez une clé dans Paramètres → Connexion, exportez-la, relancez la session. Sur Claude Code, préférez le connecteur OAuth : aucune clé à gérer.
• Résultat attendu — get_workflow répond sans erreur.

`codboard` n’apparaît pas dans `/mcp`

• Symptôme — dans Claude Code, /mcp ne liste pas codboard, et les outils (get_workflow, create_request…) sont introuvables.
• Cause probable — plugin non installé/activé, ou serveur .mcp.json de projet non approuvé, ou (config manuelle) champ "type": "http" manquant — Claude Code traite alors l’entrée comme du stdio et l’ignore.
• Diagnostic — claude plugin list doit montrer codboard@badjilounes activé ; en config manuelle, vérifiez la présence de "type": "http".
• Correction — réinstallez le plugin, approuvez le serveur au premier lancement, ou ajoutez "type": "http". Redémarrez la session.
• Résultat attendu — /mcp affiche codboard connecté et les skills du watcher chargées.

`get_workflow` renvoie un workflow vide

• Symptôme — get_workflow répond, mais sans statuts, transitions ni playbook ; les portes Testing et Rapport restent inactives.
• Cause probable — aucun workflow n’est configuré pour ce projet : l’appel réussit et renvoie un workflow indéfini (ce n’est pas une erreur).
• Diagnostic — ouvrez le board du projet : la section Workflow est-elle vide ?
• Correction — définissez statuts, transitions et playbook (voir Workflow).
• Résultat attendu — get_workflow renvoie vos statuts, transitions gardées et règles de playbook.

« Project / Repository not found »

• Symptôme — les outils renvoient 404 · Project with ID … not found ou Repository with ID … not found.
• Cause probable — le projectId/repositoryId de .codboard/config.json est erroné, ou la ressource appartient à un autre workspace que celui de votre clé/session (l’isolation la masque en 404).
• Diagnostic — comparez les IDs du fichier avec ceux du boardUrl de votre projet.
• Correction — relancez /codboard:init pour réécrire un pointeur correct, ou corrigez les IDs à la main, puis committez.
• Résultat attendu — get_project et list_tasks répondent pour le bon projet.

`.codboard/config.json` ignoré

• Symptôme — la sync ne se déclenche pas : branches/PR non reflétées, aucun blocage de hook, comme si le dépôt n’était pas suivi.
• Cause probable — le fichier est absent, malformé, ou n’a pas été committé. Les hooks no-op silencieusement hors d’un dépôt tracké (toute erreur interne → sortie 0).
• Diagnostic — confirmez que .codboard/config.json existe à la racine et que son JSON est valide (cat .codboard/config.json).
• Correction — relancez /codboard:init, relisez le fichier, committez-le.
• Résultat attendu — les milestones (branche, PR, statut) sont miroités sur le board au moment où ils arrivent.

Codex : le serveur HTTP ne se connecte pas

• Symptôme — dans Codex CLI, le serveur codboard défini avec url = … ne se connecte pas.
• Cause probable — Codex trop ancien : le HTTP streamable n’était pas géré nativement (transport stdio uniquement).
• Diagnostic — codex --version ; le HTTP natif n’est présent que sur les versions récentes.
• Correction — mettez Codex à jour, ou utilisez un pont stdio→HTTP : command = "npx", args = ["-y", "mcp-remote", "https://mcp.codboard.com/mcp", "--header", "x-api-key:${CODBOARD_API_KEY}"].
• Résultat attendu — Codex liste codboard parmi ses serveurs MCP connectés.

CI verte, mais pas d’auto-merge

• Symptôme — la PR est verte, mais l’agent ne fusionne pas.
• Cause probable — autoMergeMode: none (le propriétaire fusionne, par défaut), le ciCheckName attendu n’est pas vert, ou une protection de branche du provider s’applique encore.
• Diagnostic — lisez la politique via get_workflow → automation.autoMergeMode et automation.ciCheckName.
• Correction — ajustez la politique si voulu, ou fusionnez vous-même. L’auto-merge est appliqué de façon déterministe : un merge qui viole la politique est bloqué à la source.
• Résultat attendu — la PR fusionne dès que les conditions de votre politique sont réunies.