Mode headless et CI/CD - Tutoriel

Ce tutoriel vous montre comment automatiser Claude Code en mode non-interactif dans vos pipelines CI/CD. Vous apprendrez à utiliser le flag -p pour exécuter des prompts en une commande, configurer GitHub Actions, parser les différents formats de sortie et orchestrer des sessions multi-turn programmatiques.

Le mode headless de Claude Code est la capacité d'exécuter l'assistant IA en ligne de commande sans interface interactive, directement dans un script ou un pipeline d'intégration continue. cette fonctionnalité transforme les workflows DevOps en permettant d'intégrer l'IA générative à chaque étape du cycle de développement.

plus de 60 % des utilisateurs avancés de Claude Code exploitent le mode headless pour automatiser des tâches de revue de code, de génération de tests et de documentation.

Pour comprendre les fondamentaux avant de plonger dans l'automatisation, consultez le tutoriel d'installation et premier lancement qui couvre la mise en place initiale de l'outil.

Quels sont les prérequis avant de commencer ?

Vérifiez que votre environnement remplit ces conditions avant de suivre ce guide pas-à-pas.

Exportez votre clé API dans votre terminal pour les étapes suivantes :

export ANTHROPIC_API_KEY="sk-ant-api03-votre-clé-ici"

En pratique, le mode headless nécessite obligatoirement la variable ANTHROPIC_API_KEY car il n'y a pas d'interface de connexion interactive. Le temps total de ce tutoriel est d'environ 30 minutes.

Si vous débutez avec les interactions en ligne de commande, le guide sur vos premières conversations vous donnera les bases nécessaires.

⚠️ Si vous voyez Error: Missing API key, vérifiez que la variable d'environnement est bien exportée dans le même shell ou dans les secrets de votre CI.

À retenir : le mode headless requiert Node.js 22+, Claude Code v1.0.32+ et une clé API configurée en variable d'environnement.

Comment utiliser le flag -p pour exécuter Claude Code en une commande ?

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 directement sur la sortie standard, sans ouvrir de session interactive.

Étape 1 : Exécutez votre première commande headless (~2 min)

Lancez Claude Code avec un prompt simple :

claude -p "Explique ce que fait le fichier package.json dans ce projet"

✅ Vérification : la réponse s'affiche directement dans le terminal, puis le processus se termine avec un code de sortie 0.

Étape 2 : Redirigez la sortie vers un fichier (~1 min)

Redirigez le résultat dans un fichier Markdown pour archivage :

claude -p "Génère la documentation des fonctions exportées" > docs/api-reference.md

✅ Vérification : ouvrez le fichier docs/api-reference.md et confirmez qu'il contient du Markdown structuré.

Étape 3 : Combinez avec des pipes Unix (~2 min)

Canalisez du contenu vers Claude Code via stdin :

cat src/utils.ts | claude -p "Ajoute des commentaires JSDoc à chaque fonction"

✅ Vérification : le code commenté s'affiche sur stdout. Le fichier original reste intact.

Concrètement, le flag -p accepte aussi l'option --max-turns pour limiter le nombre d'itérations de l'agent. Par défaut, Claude Code effectue jusqu'à 10 tours en mode headless.

Pour maîtriser la gestion du contexte lors des sessions longues, référez-vous au tutoriel sur la gestion du contexte.

⚠️ Si vous voyez Error: stdin is not a TTY, cela signifie que Claude Code tente d'ouvrir le mode interactif dans un environnement non-TTY. Ajoutez le flag -p pour forcer le mode headless.

À retenir : le flag -p transforme Claude Code en outil CLI classique compatible avec les pipes, redirections et scripts shell.

Comment intégrer Claude Code dans GitHub Actions ?

GitHub Actions est la plateforme CI/CD la plus utilisée avec Claude Code en mode headless. Voici comment configurer un workflow complet.

Étape 4 : Créez le fichier workflow (~3 min)

Créez le répertoire et le fichier de configuration GitHub Actions :

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

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

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

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

      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          echo "$DIFF" | claude -p \
            "Analyse ce diff. Liste les bugs potentiels, problèmes de sécurité et suggestions d'amélioration. Format: Markdown." \
            --output-format text > review.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Revue Claude Code\n\n${review}`
            });

✅ Vérification : poussez ce fichier sur une branche, ouvrez une PR et observez le commentaire de revue automatique.

Le système de permissions et sécurité vous permettra de contrôler précisément les actions que Claude Code peut effectuer dans votre pipeline.

Étape 5 : Sécurisez le secret API (~2 min)

Ajoutez votre clé API dans les secrets du dépôt GitHub :

gh secret set ANTHROPIC_API_KEY --body "sk-ant-api03-votre-clé"

les secrets sont chiffrés avec libsodium et ne sont jamais exposés dans les logs. En pratique, le coût moyen d'une revue de code par Claude Code est d'environ 0.03 $ par exécution pour un diff de 500 lignes.

⚠️ Si vous voyez Error: Resource not accessible by integration, vérifiez les permissions du workflow dans le bloc permissions du YAML.

À retenir : un workflow GitHub Actions de revue automatique se met en place en 5 minutes avec un seul fichier YAML et un secret API.

Quels formats de sortie choisir et comment les parser ?

Claude Code propose trois formats de sortie en mode headless : text, json et stream-json. Chaque format répond à un besoin spécifique dans vos scripts d'automatisation.

Étape 6 : Explorez les trois formats de sortie (~3 min)

Testez chaque format pour comprendre leur structure :

# Format texte brut (défaut)
claude -p "Liste 3 bonnes pratiques TypeScript" --output-format text

# Format JSON structuré
claude -p "Liste 3 bonnes pratiques TypeScript" --output-format json

# Format JSON en streaming
claude -p "Liste 3 bonnes pratiques TypeScript" --output-format stream-json

Le format json retourne un objet structuré avec les métadonnées complètes de la réponse. La latence moyenne du premier token est de 800 ms en mode headless.

Étape 7 : Parsez la sortie JSON avec jq (~2 min)

Extrayez le contenu de la réponse avec jq :

claude -p "Analyse la complexité de ce code" --output-format json | jq -r '.result'

Pour extraire le coût de la requête en tokens :

claude -p "Résume ce fichier" --output-format json | jq '{
  input_tokens: .usage.input_tokens,
  output_tokens: .usage.output_tokens,
  cost_usd: .usage.cost_usd
}'

En pratique, le format JSON contient 12 champs dont result, usage, model, session_id et is_error. Pour un panorama rapide des options disponibles, consultez l'aide-mémoire du mode headless.

✅ Vérification : la commande jq doit retourner un objet JSON avec les champs input_tokens et output_tokens renseignés.

Étape 8 : Traitez le streaming en temps réel (~3 min)

Parsez le flux stream-json ligne par ligne en Python :

import subprocess
import json

process = subprocess.Popen(
    ["claude", "-p", "Génère 5 tests unitaires", "--output-format", "stream-json"],
    stdout=subprocess.PIPE,
    text=True
)

for line in process.stdout:
    event = json.loads(line.strip())
    if event.get("type") == "assistant":
        print(event["content"], end="", flush=True)

Le format stream-json émet un événement JSON par ligne, avec un débit moyen de 40 tokens par seconde. Chaque événement contient un champ type qui vaut assistant, tool_use, tool_result ou system.

⚠️ Si vous voyez des erreurs de parsing JSON, vérifiez que vous lisez bien ligne par ligne et non le flux complet d'un coup.

À retenir : utilisez text pour les scripts simples, json pour le post-traitement structuré et stream-json pour l'affichage progressif.

Comment orchestrer des sessions multi-turn programmatiques ?

Une session multi-turn permet d'enchaîner plusieurs prompts dans un même contexte conversationnel, ce qui est indispensable pour les tâches complexes nécessitant plusieurs étapes.

Étape 9 : Reprenez une session existante (~3 min)

Lancez une première commande et récupérez l'identifiant de session :

# Première commande : récupérer le session_id
SESSION=$(claude -p "Analyse la structure du projet" \
  --output-format json | jq -r '.session_id')

echo "Session ID: $SESSION"

# Deuxième commande : continuer dans le même contexte
claude -p "Maintenant génère les tests pour les fichiers identifiés" \
  --session-id "$SESSION" \
  --output-format json | jq -r '.result'

Concrètement, le session_id conserve tout le contexte de la conversation précédente. La fenêtre de contexte supporte jusqu'à 200 000 tokens en mode headless.

Le système de mémoire CLAUDE.md complète cette approche en persistant les instructions entre les sessions.

Étape 10 : Scriptez un workflow multi-étapes (~5 min)

Créez un script Bash orchestrant plusieurs étapes avec contexte partagé :

#!/bin/bash
set -euo pipefail

PROJECT_DIR=$(pwd)
OUTPUT_DIR="$PROJECT_DIR/.claude-ci"
mkdir -p "$OUTPUT_DIR"

# Étape 1 : Analyse
echo "🔍 Analyse du projet..."
RESULT=$(claude -p "Analyse les fichiers modifiés dans le dernier commit. \
  Liste les fichiers et leur rôle." \
  --output-format json)

SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
echo "$RESULT" | jq -r '.result' > "$OUTPUT_DIR/analysis.md"

# Étape 2 : Génération de tests
echo "🧪 Génération des tests..."
claude -p "Pour chaque fichier identifié, génère un test unitaire Jest." \
  --session-id "$SESSION_ID" \
  --output-format json | jq -r '.result' > "$OUTPUT_DIR/tests.md"

# Étape 3 : Revue de sécurité
echo "🔒 Revue de sécurité..."
claude -p "Identifie les vulnérabilités potentielles dans ces fichiers." \
  --session-id "$SESSION_ID" \
  --output-format json | jq -r '.result' > "$OUTPUT_DIR/security.md"

echo "✅ Pipeline terminé. Résultats dans $OUTPUT_DIR/"

✅ Vérification : exécutez le script et vérifiez que les trois fichiers Markdown sont créés dans .claude-ci/.

Pour restreindre les outils accessibles à Claude Code dans vos scripts automatisés, le tutoriel sur les permissions et sécurité détaille chaque option.

⚠️ Si vous voyez Error: Session not found, le session_id a expiré. Les sessions headless ont une durée de vie de 15 minutes par défaut. Relancez une nouvelle session.

À retenir : les sessions multi-turn avec --session-id permettent de chaîner des tâches complexes tout en conservant le contexte conversationnel.

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

Au-delà de la revue de code, le mode headless ouvre des possibilités d'automatisation avancée dans vos pipelines.

Étape 11 : Automatisez la génération de changelogs (~3 min)

Configurez un job de génération automatique de changelog :

#!/bin/bash
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~10")

git log "$LAST_TAG"..HEAD --pretty=format:"%h %s" | claude -p \
  "Transforme cette liste de commits en changelog structuré. \
   Catégories : Features, Bug Fixes, Performance, Breaking Changes. \
   Format Markdown avec liens vers les commits." \
  --output-format text > CHANGELOG-draft.md

le mode headless traite en moyenne 15 000 tokens d'entrée par requête dans les pipelines CI/CD. Cette automatisation réduit de 85 % le temps de rédaction manuelle des changelogs.

Étape 12 : Créez un gate de qualité avec score (~3 min)

Implémentez un quality gate qui bloque la PR si le score est insuffisant :

#!/bin/bash
SCORE=$(claude -p "Analyse ce diff et attribue un score de qualité de 0 à 100. \
  Critères : lisibilité, couverture d'erreurs, conventions. \
  Réponds UNIQUEMENT avec le nombre." \
  --output-format text | tr -d '[:space:]')

echo "Score de qualité : $SCORE/100"

if [ "$SCORE" -lt 70 ]; then
  echo "❌ Score insuffisant ($SCORE < 70). PR bloquée."
  exit 1
fi

echo "✅ Score acceptable ($SCORE >= 70). PR validée."

Vous pouvez explorer d'autres astuces d'utilisation du mode headless pour affiner vos automatisations.

Utilisation avec d'autres plateformes CI

Le mode headless fonctionne avec toutes les plateformes CI/CD majeures. Adaptez la configuration selon votre environnement :

En pratique, 92 % des équipes utilisant Claude Code en CI/CD choisissent GitHub Actions comme plateforme principale, suivi de GitLab CI à 5 %.

Consultez la FAQ du mode headless pour les questions fréquentes sur la compatibilité multi-plateformes.

✅ Vérification : exécutez votre script de quality gate sur un fichier de test et vérifiez qu'il retourne un score numérique.

À retenir : le mode headless s'adapte à tous les cas d'usage CI/CD - changelogs, quality gates, documentation, tests - sur n'importe quelle plateforme.

Comment sécuriser et optimiser vos pipelines headless ?

La sécurité et la performance sont des préoccupations majeures quand vous intégrez une IA dans vos pipelines automatisés.

Restreignez les outils disponibles avec --allowedTools pour limiter la surface d'attaque :

# Lecture seule : Claude ne peut que lire et chercher
claude -p "Analyse ce code" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json

Le flag --allowedTools accepte une liste séparée par des virgules. En mode CI/CD, SFEIR Institute recommande de toujours restreindre les outils au strict nécessaire. L'outil Bash doit être exclu dans les pipelines de revue pour éviter toute exécution de code non contrôlée.

Pour maîtriser les commandes essentielles disponibles dans Claude Code, référez-vous au tutoriel des commandes slash.

Le coût moyen d'une exécution headless est de 0.01 à 0.05 $ selon la taille du contexte. Pour un pipeline traitant 50 PRs par jour, cela représente environ 50 $ par mois.

Si vous souhaitez approfondir l'ensemble des possibilités du mode headless et CI/CD, la page de référence couvre chaque option en détail.

⚠️ Si vous voyez Error: Tool not allowed, vérifiez que l'outil requis par le prompt est bien dans la liste --allowedTools.

À retenir : restreignez toujours les outils au minimum nécessaire et budgétisez vos coûts API en fonction du volume de PRs.

Comment aller plus loin avec Claude Code en CI/CD ?

Ce tutoriel vous a montré les fondamentaux du mode headless. Voici les prochaines étapes pour approfondir votre maîtrise.

Explorez ces ressources complémentaires pour perfectionner votre configuration :

1. Mémoire persistante : le système CLAUDE.md permet de stocker des instructions réutilisables entre sessions headless
2. Formats avancés : l'aide-mémoire du mode headless résume toutes les options CLI en une page
3. Dépannage : la FAQ du mode headless couvre les 15 erreurs les plus fréquentes
4. Bonnes pratiques : les astuces avancées détaillent les patterns d'automatisation éprouvés

Pour monter en compétence de manière structurée, SFEIR Institute propose la formation Claude Code sur une journée, avec des labs pratiques couvrant le mode headless et l'intégration CI/CD. Si vous souhaitez aller au-delà et intégrer l'IA dans l'ensemble de votre workflow de développement, la formation Développeur Augmenté par l'IA sur deux jours aborde les stratégies d'automatisation complètes.

Pour les praticiens déjà expérimentés, la formation Développeur Augmenté par l'IA – Avancé en une journée approfondit les cas d'usage CI/CD avancés et les architectures multi-agents.

Le mode headless est un outil qui se perfectionne avec la pratique. Commencez par un cas d'usage simple - la revue de code automatique - puis élargissez progressivement votre couverture d'automatisation.

À retenir : le mode headless de Claude Code transforme votre pipeline CI/CD en un assistant intelligent capable d'analyser, générer et valider du code à chaque commit.