Mode headless et CI/CD - Aide-memoire

Cet aide-mémoire rassemble toutes les commandes pour utiliser Claude Code en mode headless dans vos pipelines CI/CD. Retrouvez la syntaxe du flag -p, les formats de sortie, les intégrations GitHub Actions et les sessions programmatiques multi-turn. Gardez cette fiche pratique sous la main pour automatiser vos workflows sans intervention humaine.

Le mode headless de Claude Code est la capacité d'exécuter l'outil en ligne de commande non interactive, sans interface conversationnelle, pour l'intégrer dans des scripts et des pipelines d'automatisation. cette fonctionnalité transforme Claude Code en brique d'automatisation pour la CI/CD, le linting IA et la revue de code automatisée.

Comment lancer Claude Code en mode headless avec le flag -p ?

Le flag -p (pour print) est le point d'entrée du mode headless. Il permet d'envoyer un prompt unique à Claude Code et de récupérer la réponse sur la sortie standard, sans ouvrir l'interface interactive. Exécutez cette commande pour un premier test :

cat src/index.ts | claude -p "Explique ce que fait ce fichier"

Claude Code traite le prompt, génère la réponse et quitte immédiatement. Le code de sortie reflète le succès (0) ou l'échec (1) de l'exécution. En pratique, la grande majorité des usages CI/CD reposent sur ce seul flag.

Pour découvrir chaque option en détail, consultez la référence complète des commandes du mode headless qui couvre l'intégralité des flags disponibles.

À retenir : le flag -p transforme Claude Code en outil CLI classique compatible avec tout pipeline d'automatisation.

Quels sont les formats de sortie disponibles pour le parsing ?

Claude Code propose trois formats de sortie via --output-format. Choisissez le format adapté à votre cas d'usage pour parser la réponse efficacement.

Format text (défaut)

claude -p "Explique cette fonction" --output-format text

Le format text renvoie la réponse brute en texte plein. Utilisez-le pour les cas simples où vous redirigez la sortie vers un fichier ou l'affichez dans les logs CI.

Format json

claude -p "Analyse ce code" --output-format json

La sortie JSON est un objet unique contenant le résultat complet. Voici la structure type :

{
 "type": "result",
 "result": "Votre réponse ici",
 "session_id": "<identifiant de session>",
 "total_cost_usd": 0.0123
}

Le champ result contient la réponse complète, le champ session_id permet de reprendre la session dans un appel ultérieur, et le champ total_cost_usd affiche le coût en dollars de l'appel sous forme de nombre (et non de chaîne). Le coût dépend de la taille du contexte et du modèle utilisé ; appuyez-vous sur le champ total_cost_usd de la sortie JSON pour connaître la valeur réelle.

Format stream-json

claude -p "Revois ce PR" --output-format stream-json | jq '.type'

Le format stream-json émet des objets JSON ligne par ligne (NDJSON). Chaque événement possède un champ type distinct. Ce format permet de traiter la réponse en temps réel sans attendre la fin de l'exécution.

Pour maîtriser la gestion des sorties dans vos scripts, la fiche pratique sur la gestion du contexte vous donne les patterns de parsing réutilisables.

À retenir : utilisez json pour les scripts automatisés et stream-json pour le feedback en temps réel.

Comment intégrer Claude Code dans GitHub Actions ?

L'intégration GitHub Actions repose sur un workflow YAML qui installe Claude Code puis l'exécute avec -p. la majorité des équipes utilisant Claude Code en CI l'intègrent via GitHub Actions. Créez un fichier .github/workflows/claude-review.yml :

name: Claude Code Review
on:
 pull_request:
 types: [opened, synchronize]

jobs:
 review:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 with:
 fetch-depth: 0

 - name: Install Claude Code
 run: npm install -g @anthropic-ai/claude-code

 - name: Run review
 env:
 ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 run: |
 claude -p "Revois les changements de ce PR et liste les problèmes potentiels" \
 --output-format json > review.json

Le secret ANTHROPIC_API_KEY est la clé API Anthropic stockée dans les secrets GitHub. Configurez-la dans Settings → Secrets → Actions de votre dépôt. La durée d'une revue dépend de la taille du diff et du modèle utilisé.

Pour sécuriser les permissions de l'outil en CI, consultez la fiche sur les permissions et la sécurité qui détaille le mode --allowedTools.

À retenir : stockez votre clé API dans les secrets GitHub et limitez les outils autorisés avec --allowedTools en CI.

Comment gérer des sessions multi-turn programmatiques ?

Une session multi-turn permet d'enchaîner plusieurs prompts dans un même contexte conversationnel. Utilisez le flag --resume pour maintenir la continuité entre les appels.

# Premier appel : démarrer une session
RESULT=$(claude -p "Analyse l'architecture du projet" \
 --output-format json)
echo "$RESULT" > step1.json
SESSION=$(echo "$RESULT" | jq -r '.session_id')

# Deuxième appel : continuer dans la même session
claude -p "Maintenant propose des améliorations" \
 --resume "$SESSION" \
 --output-format json > step2.json

Le flag --resume suivi d'un identifiant de session indique à Claude Code de charger le contexte de la session existante. Le flag --continue (sans argument) reprend la dernière session. Chaque session conserve le contexte dans la limite de la fenêtre de contexte du modèle utilisé.

En pratique, les sessions multi-turn consomment davantage de tokens par rapport à des appels isolés. Limitez le nombre de tours avec --max-turns pour maîtriser les coûts.

Pour structurer vos conversations programmatiques, la fiche sur vos premières conversations explique les patterns conversationnels fondamentaux que vous retrouverez en mode headless.

À retenir : récupérez le session_id depuis la réponse JSON et reprenez vos sessions avec --resume pour des workflows multi-étapes.

Quels sont les cas d'usage CI/CD avancés ?

Le mode headless de Claude Code couvre des scénarios bien au-delà de la simple revue de code. Voici concrètement les cas d'usage les plus courants.

Génération automatique de tests

claude -p "Génère des tests unitaires pour src/auth.ts avec vitest" \
 --allowedTools Read,Write \
 --max-turns 5 \
 --output-format json

Les tests générés peuvent compléter la couverture existante ; vérifiez toujours leur pertinence. Limitez les outils à Read,Write pour empêcher l'exécution de commandes non contrôlées.

Linting et correction automatique

claude -p "Corrige les erreurs ESLint dans src/ sans changer la logique" \
 --allowedTools Read,Write \
 --output-format text

Un pipeline de correction automatique réduit le travail manuel de résolution des erreurs de lint. Vérifiez toujours le diff généré avant de merger automatiquement.

Documentation automatique

claude -p "Génère la JSDoc pour toutes les fonctions exportées de lib/" \
 --allowedTools Read,Write \
 --max-turns 10

Pour explorer d'autres exemples concrets de pipelines, la page exemples du mode headless propose des workflows prêts à l'emploi.

Le guide complet du mode headless et CI/CD détaille chaque scénario avec des architectures de pipeline complètes.

À retenir : restreignez toujours les outils autorisés (--allowedTools) en CI pour limiter la surface d'action de l'IA.

Comment sécuriser l'exécution de Claude Code en CI/CD ?

La sécurité en CI/CD exige de restreindre les capacités de Claude Code. Appliquez ces 5 règles systématiquement.

1. Limitez les outils avec --allowedTools Read,Write - jamais Bash en CI automatique
2. Stockez la clé API dans un gestionnaire de secrets (GitHub Secrets, Vault, AWS SSM)
3. Fixez --max-turns à une valeur raisonnable (3 à 10) pour éviter les boucles infinies
4. Validez la sortie JSON avec un schéma avant d'agir sur le résultat
5. Auditez chaque exécution en conservant les logs (--verbose > claude-audit.log)

claude -p "Revois ce code" \
 --allowedTools Read \
 --max-turns 3 \
 --verbose \
 --output-format json 2>claude-audit.log

Le coût d'une exécution CI dépend de la taille du contexte, du modèle et du nombre de tours ; appuyez-vous sur le champ total_cost_usd de la sortie JSON pour suivre le coût réel de chaque run.

Pour comprendre le modèle de permissions en profondeur, la fiche sur les permissions et la sécurité vous guide pas à pas. Pensez aussi à consulter les erreurs courantes du mode headless pour anticiper les pièges fréquents.

À retenir : le trio --allowedTools, --max-turns et --verbose constitue le socle de sécurité minimal en CI.

Quels raccourcis et variables d'environnement connaître ?

En mode headless, les raccourcis clavier n'existent pas (pas d'interface interactive). En revanche, plusieurs variables d'environnement contrôlent le comportement de Claude Code en CI.

Définissez la clé API dans votre fichier CI et utilisez les flags en ligne de commande pour les autres options :

export ANTHROPIC_API_KEY="sk-ant-..."
claude -p "Analyse ce projet" --max-turns 5 --output-format json

Veillez à utiliser une version récente de Claude Code dans votre environnement CI pour bénéficier des dernières améliorations du mode headless.

La fiche d'installation et premier lancement détaille la configuration initiale nécessaire avant d'utiliser le mode headless. Vous trouverez aussi dans la fiche sur les commandes slash les commandes utiles pour configurer Claude Code avant de l'automatiser.

À retenir : configurez les variables d'environnement une fois dans votre CI pour simplifier tous vos appels headless.

Comment déboguer un pipeline Claude Code qui échoue ?

Quand un pipeline échoue, suivez cette procédure de diagnostic en 4 étapes.

1. Vérifiez le code de sortie : echo $? après l'appel (0 = succès, 1 = erreur)
2. Activez --verbose pour obtenir les logs détaillés sur stderr
3. Inspectez la sortie JSON : le champ is_error signale l'échec et le champ result contient le message d'erreur
4. Testez localement avec le même prompt avant de relancer le pipeline

# Diagnostic complet
claude -p "Mon prompt" \
 --output-format json \
 --verbose 2>debug.log

# Vérifier le code de sortie
echo "Exit code: $?"

# Lire les logs
cat debug.log

Les erreurs les plus fréquentes en CI sont généralement : une clé API invalide ou manquante, le dépassement du --max-turns et les timeouts réseau.

Pour une liste exhaustive des messages d'erreur et leurs solutions, consultez le guide erreurs courantes du mode headless. L'aide-mémoire sur l'intégration Git vous aide aussi à résoudre les problèmes liés aux opérations Git dans vos pipelines.

À retenir : --verbose et le code de sortie sont vos deux premiers réflexes de débogage en CI.

Faut-il suivre une formation pour maîtriser Claude Code en CI/CD ?

Automatiser Claude Code en CI/CD demande de comprendre les flags, les formats de sortie, les sessions et les bonnes pratiques de sécurité. SFEIR Institute propose des formations structurées pour accélérer cette montée en compétences.

La formation Claude Code d'une journée vous fait pratiquer le mode headless sur des labs concrets : vous construisez un pipeline GitHub Actions complet et configurez les permissions de sécurité de bout en bout.

Pour aller plus loin, la formation Développeur Augmenté par l'IA sur 2 jours couvre l'ensemble des outils IA pour développeurs, dont l'intégration CI/CD avancée avec sessions multi-turn et parsing JSON.

Les développeurs expérimentés peuvent suivre le module Développeur Augmenté par l'IA – Avancé d'une journée, axé sur les architectures de pipelines complexes et l'optimisation des coûts API en production.

À retenir : les formations SFEIR Institute combinent théorie et labs pratiques pour vous rendre opérationnel sur Claude Code en CI/CD dès le premier jour.