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 Preuves 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 — parfois en le disant : « la vérif est verte, mais je te laisse le merge ».
• Cause probable — le plugin n’est pas chargé : c’est le cas le plus fréquent quand l’agent cite la bonne politique et rend quand même la main. Le serveur MCP est configuré à part, il lit donc list_repositories très bien — mais sans le plugin, rien ne lui dit que le mode est l’autorisation, et il se rabat sur sa prudence par défaut. Sinon : autoMergeMode: none (le propriétaire fusionne, par défaut), le ciCheckName attendu qui n’est pas vert, ou une protection de branche du provider.
• Diagnostic — d’abord le plugin : le .claude/settings.json committé doit porter les deux clés, extraKnownMarketplaces.badjilounes et enabledPlugins["codboard@badjilounes"] — une install CLI vit dans ~/.claude/ et ne survit pas à une session hébergée. Ensuite la politique du dépôt via list_repositories → automation.autoMergeMode et automation.ciCheckName ; côté interface, le badge de la ligne du dépôt (Réglages du projet → Repositories) l’affiche directement. Ce n’est pas get_workflow : la politique de merge a quitté le workflow pour le dépôt.
• Correction — relancez /codboard:init : sur un dépôt déjà relié, il écrit les clés manquantes sans rien écraser. Committez le fichier. Si le plugin était bien là, ajustez la politique dans Réglages du projet → Repositories → crayon du dépôt, ou fusionnez vous-même.
• Résultat attendu — la PR fusionne dès que la barrière du mode est satisfaite, sans que l’agent repose la question ; si elle ne l’est pas, il dit pourquoi au lieu de rendre la main.