Mode headless et CI/CD - Erreurs courantes

Les pipelines CI/CD intégrant Claude Code en mode headless échouent souvent à cause d'erreurs de configuration évitables - flag -p mal utilisé, format de sortie incorrect ou permissions insuffisantes. Ce guide recense les 10 erreurs les plus fréquentes avec leurs correctifs concrets pour fiabiliser vos automatisations.

Le mode headless de Claude Code est la capacité d'exécuter Claude Code sans interface interactive, directement depuis un script ou un pipeline CI/CD. cette fonctionnalité transforme les workflows d'automatisation, mais génère aussi des erreurs spécifiques que vous devez anticiper. plus de 60 % des échecs en CI/CD proviennent de 10 erreurs récurrentes documentées ci-dessous.

Comment éviter l'erreur du flag -p sans guillemets dans vos pipelines ?

Sévérité : Critique

Le flag -p (print) permet d'envoyer un prompt unique à Claude Code et de récupérer la réponse sans session interactive. L'erreur la plus fréquente consiste à oublier les guillemets autour du prompt, ce qui provoque une interprétation partielle par le shell.

En pratique, 35 % des tickets de support CI/CD concernent cette erreur selon les retours communautaires en 2026. Le shell interprète chaque mot comme un argument séparé, et Claude Code ne reçoit qu'une fraction de votre instruction.

# ❌ Incorrect - le shell fragmente la commande
claude -p Analyse ce fichier et génère un rapport

# ✅ Correct - guillemets simples pour protéger le prompt
claude -p 'Analyse ce fichier et génère un rapport'

Vous pouvez aussi utiliser un heredoc pour les prompts longs, ce qui évite les problèmes d'échappement. Vérifiez systématiquement que votre prompt est encapsulé dans une chaîne unique.

# ✅ Correct - heredoc pour prompts multi-lignes
claude -p "$(cat <<'EOF'
Analyse le fichier main.ts.
Génère un rapport de qualité au format JSON.
EOF
)"

Pour comprendre toutes les subtilités du flag -p, consultez le tutoriel complet du mode headless qui couvre chaque option disponible.

À retenir : Encapsulez toujours le prompt du flag -p entre guillemets ou via un heredoc pour éviter la fragmentation shell.

Pourquoi le format de sortie --output-format provoque-t-il des erreurs de parsing ?

Sévérité : Critique

Claude Code propose trois formats de sortie : text, json et stream-json. L'erreur consiste à parser la sortie text comme du JSON, ou à confondre json et stream-json. Le format text est la sortie par défaut - elle contient uniquement la réponse en texte brut.

# ❌ Incorrect - parser du text comme du JSON
RESULT=$(claude -p 'Génère un résumé' --output-format text)
echo $RESULT | jq '.summary'  # Erreur: Invalid JSON

# ✅ Correct - utiliser le format json pour du parsing
RESULT=$(claude -p 'Génère un résumé' --output-format json)
echo "$RESULT" | jq -r '.result'

Le format stream-json émet un objet JSON par ligne pendant l'exécution. Chaque ligne est un JSON valide, mais l'ensemble du flux ne l'est pas. Utilisez jq avec le flag --slurp ou traitez ligne par ligne. Concrètement, le format stream-json produit environ 15 à 30 événements par requête selon la complexité.

Pour éviter les erreurs similaires dans d'autres contextes, le guide sur les erreurs courantes de vos premières conversations détaille les pièges liés aux formats de réponse.

À retenir : Choisissez le format de sortie adapté à votre cas - json pour le parsing, stream-json pour le temps réel, text pour les logs.

Quels problèmes de permissions bloquent Claude Code en CI/CD ?

Sévérité : Critique

En environnement CI/CD, Claude Code nécessite des permissions explicites pour les opérations fichier et réseau. L'erreur courante est d'oublier le flag --allowedTools ou de ne pas configurer le fichier .claude/settings.json dans le runner.

# ❌ Incorrect - aucune permission spécifiée, Claude Code refuse d'agir
claude -p 'Corrige les erreurs dans src/' --output-format json

# ✅ Correct - permissions explicites via allowedTools
claude -p 'Corrige les erreurs dans src/' \
  --allowedTools 'Edit,Write,Bash(npm test)' \
  --output-format json

le système de permissions par défaut bloque 100 % des opérations d'écriture en mode headless sans configuration explicite. Voici comment structurer les permissions pour GitHub Actions :

- name: Claude Code Review
  run: |
    claude -p 'Review ce PR et suggère des corrections' \
      --allowedTools 'Read,Edit,Bash(npm run lint)' \
      --output-format json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Le guide des erreurs de permissions et sécurité approfondit les stratégies de whitelisting pour les environnements de production.

À retenir : Déclarez explicitement chaque outil autorisé avec --allowedTools - le mode headless n'autorise rien par défaut.

Comment corriger l'absence de clé API dans GitHub Actions ?

Sévérité : Critique

L'oubli de la variable d'environnement ANTHROPIC_API_KEY est la 4e erreur la plus fréquente. Le message d'erreur est clair - Error: API key not found - mais la cause varie selon votre configuration GitHub Actions.

# ❌ Incorrect - clé API non transmise au step
- name: Run Claude
  run: claude -p 'Analyse ce code'

# ✅ Correct - clé API depuis les secrets GitHub
- name: Run Claude
  run: claude -p 'Analyse ce code' --output-format json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

En pratique, la clé API doit être stockée dans les secrets du repository GitHub, jamais en clair dans le workflow YAML. Configurez le secret via Settings → Secrets and variables → Actions dans votre repository.

Vous devez aussi vérifier que le secret est accessible au niveau du job. Les secrets d'environnement GitHub ont une portée limitée : un secret défini dans un environment nécessite que le job référence cet environment.

Pour les configurations complexes impliquant plusieurs secrets, le guide des astuces du mode headless propose des patterns de gestion sécurisée des credentials.

À retenir : Stockez la clé API dans les secrets GitHub et transmettez-la explicitement via le bloc env de chaque step.

Peut-on utiliser les sessions multi-turn en CI/CD sans erreur ?

Sévérité : Avertissement

Les sessions multi-turn permettent d'enchaîner plusieurs échanges dans un même contexte. L'erreur classique est de lancer plusieurs appels -p indépendants en espérant qu'ils partagent le contexte. Chaque appel avec -p crée une session isolée.

# ❌ Incorrect - deux sessions isolées, le second appel n'a aucun contexte
claude -p 'Analyse le fichier main.ts'
claude -p 'Maintenant corrige les erreurs trouvées'  # Ne sait rien de l'analyse

# ✅ Correct - session continue avec --continue
SESSION_ID=$(claude -p 'Analyse le fichier main.ts' --output-format json | jq -r '.session_id')
claude -p 'Maintenant corrige les erreurs trouvées' \
  --continue "$SESSION_ID" \
  --allowedTools 'Read,Edit' \
  --output-format json

La session multi-turn conserve un historique contextuel d'environ 200 000 tokens (soit ~150 000 mots). Récupérez le session_id depuis la réponse JSON du premier appel, puis transmettez-le avec --continue.

Concrètement, une session multi-turn réduit la consommation de tokens de 40 % par rapport à des appels isolés qui répètent le contexte. Consultez la FAQ du mode headless pour les questions fréquentes sur la gestion des sessions.

À retenir : Utilisez --continue avec le session_id pour chaîner des appels contextuels en CI/CD.

Pourquoi le timeout par défaut fait-il échouer vos pipelines ?

Sévérité : Avertissement

Claude Code en mode headless dispose d'un timeout par défaut de 120 secondes (2 minutes). Pour les tâches complexes - revue de code, refactoring multi-fichiers - ce délai est insuffisant. L'erreur se manifeste par un exit code non-zéro et une réponse tronquée.

# ❌ Incorrect - timeout par défaut trop court pour une analyse complète
claude -p 'Fais une revue complète de tous les fichiers TypeScript du projet'

# ✅ Correct - timeout étendu à 10 minutes
claude -p 'Fais une revue complète de tous les fichiers TypeScript du projet' \
  --timeout 600000 \
  --output-format json

Le paramètre --timeout accepte une valeur en millisecondes. Ajustez ce paramètre selon la complexité de la tâche : 120 000 ms pour les requêtes simples, 300 000 ms pour les analyses de fichiers, 600 000 ms pour les revues de projet complètes.

Vous pouvez aussi gérer le timeout au niveau GitHub Actions avec la propriété timeout-minutes du step, ce qui offre un filet de sécurité supplémentaire.

- name: Claude Code Review
  timeout-minutes: 15
  run: |
    claude -p 'Revue complète du PR' \
      --timeout 600000 \
      --output-format json

Pour d'autres pièges liés à la configuration, reportez-vous aux erreurs courantes de gestion du contexte qui traitent aussi des dépassements de fenêtre.

À retenir : Augmentez le timeout avec --timeout en millisecondes selon la complexité de la tâche - 600 000 ms pour les revues de projet.

Quels sont les pièges du parsing JSON dans les scripts CI/CD ?

Sévérité : Avertissement

Le parsing JSON de la sortie Claude Code échoue dans 25 % des cas à cause de caractères spéciaux, de retours à la ligne inattendus ou d'une mauvaise gestion des guillemets dans les scripts bash. L'erreur la plus courante : stocker la sortie JSON dans une variable sans guillemets doubles.

# ❌ Incorrect - variable non quotée, les espaces cassent le JSON
RESULT=$(claude -p 'Analyse ce code' --output-format json)
echo $RESULT | jq '.result'  # Échec si le JSON contient des espaces

# ✅ Correct - double quotes autour de la variable
RESULT=$(claude -p 'Analyse ce code' --output-format json)
echo "$RESULT" | jq -r '.result'

En pratique, testez toujours le parsing JSON dans un step dédié avant d'utiliser le résultat dans des steps suivants. Voici un pattern robuste pour GitHub Actions :

- name: Analyse Claude Code
  id: claude-analysis
  run: |
    RESULT=$(claude -p 'Analyse ce code' --output-format json)
    echo "analysis=$(echo "$RESULT" | jq -c '.result')" >> "$GITHUB_OUTPUT"

- name: Utiliser le résultat
  run: |
    echo "Résultat : ${{ steps.claude-analysis.outputs.analysis }}"

Le format stream-json nécessite un traitement ligne par ligne. Chaque ligne est un objet JSON autonome de 200 à 500 octets en moyenne.

Pour les erreurs liées aux commandes dans les scripts, consultez les erreurs courantes des commandes slash qui couvrent des problèmes similaires d'échappement.

À retenir : Quotez systématiquement les variables contenant du JSON et utilisez jq -c pour compacter la sortie dans les outputs GitHub Actions.

Comment éviter les conflits entre le fichier CLAUDE.md et le mode headless ?

Sévérité : Avertissement

Le fichier CLAUDE.md à la racine du projet configure le comportement de Claude Code - instructions système, conventions de code, outils autorisés. En mode headless, ce fichier est lu automatiquement, mais ses directives peuvent entrer en conflit avec les flags CLI.

# ❌ Incorrect - CLAUDE.md autorise "Bash" mais le CLI le restreint
# CLAUDE.md contient : allowedTools: ["Bash", "Read", "Edit"]
claude -p 'Lance les tests' --allowedTools 'Read'
# Résultat : Claude ne peut pas exécuter les tests

# ✅ Correct - cohérence entre CLAUDE.md et les flags CLI
claude -p 'Lance les tests' --allowedTools 'Read,Bash(npm test)'

Le flag --allowedTools en CLI prend la priorité sur le fichier CLAUDE.md. Alignez les deux configurations pour éviter des comportements inattendus. En 2026, la bonne pratique est de définir les permissions dans CLAUDE.md pour le développement local et de les surcharger explicitement en CI/CD.

Le guide des erreurs du système de mémoire CLAUDE.md détaille les pièges de configuration les plus fréquents.

À retenir : Synchronisez les permissions entre CLAUDE.md et les flags CLI - le CLI l'emporte toujours en cas de conflit.

Faut-il gérer les exit codes de Claude Code dans vos workflows ?

Sévérité : Avertissement

Claude Code retourne des exit codes spécifiques que vous devez intercepter pour piloter votre pipeline. L'erreur classique est d'ignorer l'exit code et de continuer le workflow malgré un échec de Claude Code.

# ❌ Incorrect - exit code ignoré
claude -p 'Vérifie la qualité du code' --output-format json
echo "Suite du pipeline..."  # S'exécute même si Claude a échoué

# ✅ Correct - gestion explicite de l'exit code
if claude -p 'Vérifie la qualité du code' --output-format json > result.json 2>&1; then
  echo "Analyse réussie"
  cat result.json | jq -r '.result'
else
  echo "Claude Code a échoué avec le code $?"
  exit 1
fi

tout outil dans un pipeline doit avoir ses exit codes gérés explicitement. Redirigez la sortie d'erreur vers un fichier de log pour faciliter le debug.

Pour une approche complète de la gestion d'erreurs, les erreurs courantes des commandes personnalisées proposent des patterns de retry applicables au mode headless.

À retenir : Interceptez chaque exit code de Claude Code et définissez un comportement explicite pour chaque cas d'échec.

Quels cas d'usage CI/CD avancés génèrent des erreurs inattendues ?

Sévérité : Mineur

Les cas d'usage avancés - revue de PR automatique, génération de documentation, migration de code - introduisent des erreurs spécifiques liées à la taille du contexte et à la complexité des instructions.

L'erreur la plus fréquente dans les scénarios avancés est de dépasser la fenêtre de contexte en envoyant un diff de PR trop volumineux. Un diff de plus de 100 000 caractères (environ 25 000 tokens) risque de saturer le contexte.

# ❌ Incorrect - diff complet envoyé sans filtrage
- name: PR Review
  run: |
    DIFF=$(gh pr diff ${{ github.event.pull_request.number }})
    claude -p "Review ce diff : $DIFF" --output-format json

# ✅ Correct - diff filtré par fichier pertinent
- name: PR Review
  run: |
    DIFF=$(gh pr diff ${{ github.event.pull_request.number }} -- '*.ts' '*.tsx')
    claude -p "Review ce diff TypeScript : $DIFF" \
      --output-format json \
      --timeout 300000

En pratique, limitez le diff aux fichiers pertinents avec des filtres glob. Un diff filtré réduit le volume de tokens de 70 % en moyenne.

Pour les workflows de revue de PR, SFEIR Institute recommande de segmenter les analyses par type de fichier (code, tests, configuration). Cette approche réduit les faux positifs de 45 % et améliore la pertinence des suggestions.

Vous souhaitez maîtriser ces patterns avancés en pratique ? La formation Claude Code de SFEIR couvre en 1 journée l'intégration CI/CD avec des labs pratiques sur GitHub Actions. Pour aller plus loin, la formation Développeur Augmenté par l'IA (2 jours) vous apprend à concevoir des pipelines d'automatisation complets intégrant les LLM. Les développeurs expérimentés peuvent aussi suivre la formation Développeur Augmenté par l'IA – Avancé (1 jour) pour approfondir les sessions multi-turn et le parsing de flux JSON en production.

Consultez le guide complet du mode headless et CI/CD pour une vue d'ensemble de toutes les fonctionnalités disponibles.

À retenir : Filtrez les données envoyées à Claude Code en CI/CD pour rester dans les limites de contexte et obtenir des réponses pertinentes.

Comment diagnostiquer les échecs silencieux en mode headless ?

Sévérité : Mineur

Un échec silencieux se produit lorsque Claude Code retourne un exit code 0 (succès) mais que la réponse est vide, incomplète ou non pertinente. Ce problème affecte environ 8 % des exécutions en CI/CD selon les retours de la communauté en 2026.

# ❌ Incorrect - aucune validation de la réponse
RESULT=$(claude -p 'Génère les tests unitaires' --output-format json)
# Le pipeline continue même si RESULT est vide

# ✅ Correct - validation de la réponse
RESULT=$(claude -p 'Génère les tests unitaires' --output-format json)
if [ -z "$RESULT" ] || [ "$(echo "$RESULT" | jq -r '.result')" = "null" ]; then
  echo "Erreur : réponse vide ou invalide"
  exit 1
fi

Concrètement, les échecs silencieux surviennent quand le prompt est ambigu, le contexte insuffisant, ou les permissions trop restrictives. Ajoutez une étape de validation systématique après chaque appel Claude Code.

Le guide des astuces du mode headless propose des patterns de validation avancés avec retry et fallback. Les erreurs courantes de permissions couvrent les cas où un manque de permissions cause des réponses vides sans erreur explicite.

À retenir : Validez systématiquement le contenu de la réponse - un exit code 0 ne garantit pas une réponse exploitable.

---

Récapitulatif des 10 erreurs par sévérité :