Claude Code en Mode Headless : Automatiser tes Pipelines CI/CD avec l'IA

Mis à jour le 3 mars 2026

Claude Code ne se limite pas au terminal interactif. Derrière l'interface conversationnelle, il y a un outil en ligne de commande capable de tourner sans intervention humaine. C'est le mode headless : tu envoies un prompt, Claude Code exécute la tâche, retourne le résultat, et quitte. Pas de terminal, pas de questions, pas d'interaction.

Pourquoi c'est important ? Parce que ça veut dire que Claude Code peut s'intégrer dans n'importe quel pipeline automatisé. GitHub Actions, GitLab CI, Jenkins, scripts shell, cron jobs. À chaque push, à chaque pull request, à chaque déploiement, tu peux déclencher Claude Code pour analyser du code, générer des tests, faire une revue automatique, ou documenter un changement. C'est de l'IA qui travaille dans tes pipelines CI/CD (Continuous Integration / Continuous Deployment — le processus automatisé qui teste, valide et déploie ton code à chaque changement).

Ce guide couvre tout : la syntaxe du mode headless, les trois formats de sortie, l'intégration GitHub Actions avec un workflow complet, le SDK TypeScript pour les cas avancés, et les bonnes pratiques de sécurité. Si tu utilises déjà les hooks Claude Code pour automatiser ton workflow local, le mode headless est l'étape suivante — automatiser côté serveur.

Le mode headless : c'est quoi ?

En temps normal, Claude Code fonctionne en mode interactif : tu tapes un message, il répond, tu continues la conversation. Le mode headless supprime cette boucle conversationnelle. Tu envoies un seul prompt, Claude Code l'exécute, et retourne le résultat. Fin.

La syntaxe de base :

claude -p "analyse ce fichier et liste les bugs potentiels"

Le flag -p (pour "prompt") est la clé. Il dit à Claude Code : "pas de terminal interactif, exécute ça directement". Tu peux aussi piper un prompt via stdin (l'entrée standard — quand tu envoies du texte d'une commande vers une autre) :

echo "explique cette fonction" | claude -p
cat mon-fichier.ts | claude -p "review ce code"
git diff HEAD~1 | claude -p "analyse les changements et identifie les risques"

Cette dernière commande est particulièrement puissante : tu prends le diff de ton dernier commit Git, tu l'envoies à Claude Code, et il t'analyse les risques en quelques secondes. C'est exactement ce qu'on va utiliser dans un pipeline CI/CD.

Le mode headless respecte tes fichiers de configuration. Le CLAUDE.md, les permissions, les hooks — tout est chargé comme en mode interactif. La seule différence : pas de conversation, pas de questions. Une entrée, une sortie.

Les 3 formats de sortie

Par défaut, Claude Code retourne du texte brut. Mais en CI/CD, tu as souvent besoin de données structurées pour que tes scripts puissent parser la réponse. Trois formats sont disponibles.

Text : le défaut

claude -p "liste les TODO dans ce projet" --output-format text

Retourne du texte lisible, exactement ce que tu verrais dans le terminal interactif. Utile pour les logs de CI/CD où un humain va lire la sortie. C'est le format par défaut — si tu ne précises rien, c'est celui-là.

JSON : pour les scripts

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

Retourne un objet JSON structuré avec toutes les métadonnées de l'exécution :

{
  "result": "L'analyse du code révèle 3 points...",
  "cost_usd": 0.0234,
  "duration_ms": 4521,
  "is_error": false,
  "session_id": "abc123-def456",
  "num_turns": 1
}

C'est le format que tu veux en CI/CD. Tu récupères le result pour l'action suivante, le cost_usd pour surveiller tes dépenses, le is_error pour gérer les erreurs, et le duration_ms pour le monitoring. Chaque champ est exploitable par tes scripts.

Stream-JSON : le temps réel

claude -p "refactore ce module" --output-format stream-json

Retourne des messages JSON ligne par ligne, en temps réel. Trois types de messages : init (début de l'exécution), assistant (réponses intermédiaires au fur et à mesure que Claude Code travaille), et result (résultat final). Ce format est utile quand tu veux afficher la progression en live dans un dashboard ou un log de CI qui supporte le streaming.

Pour la majorité des cas en CI/CD, --output-format json est le bon choix. Tu récupères tout ce dont tu as besoin en un seul objet parseable.

Intégrer Claude Code dans GitHub Actions

Passons au concret. Voici un workflow GitHub Actions complet qui lance Claude Code en mode headless pour faire une code review automatique sur chaque pull request.

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

permissions:
  contents: read
  pull-requests: write

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

      - name: Installer Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Récupérer le diff de la PR
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > pr_diff.txt

      - name: Analyse par Claude Code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cat pr_diff.txt | claude -p \
            "Analyse ce diff de pull request. Identifie : bugs potentiels, \
            failles de sécurité, problèmes de performance, code mort. \
            Formate ta réponse en Markdown." \
            --output-format json \
            --allowedTools "Read,Grep,Glob" \
            --permission-mode default > review_result.json

      - name: Poster le commentaire sur la PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const result = JSON.parse(fs.readFileSync('review_result.json', 'utf8'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## Code Review par Claude Code\n\n${result.result}\n\n---\n*Coût: $${result.cost_usd} | Durée: ${result.duration_ms}ms*`
            });

Décomposons les points clés de ce workflow :

• fetch-depth: 0 — on clone tout l'historique Git pour que le diff entre la branche de base et la PR soit disponible.
• ANTHROPIC_API_KEY — la clé API est stockée dans les secrets GitHub, jamais en dur dans le code. C'est non-négociable.
• --allowedTools "Read,Grep,Glob" — on restreint Claude Code à la lecture seule. Pas de Bash, pas de Write, pas de Edit. En CI/CD, tu ne veux pas qu'une IA modifie du code sans contrôle.
• --output-format json — on récupère un objet structuré qu'on parse dans l'étape suivante pour poster le commentaire.

C'est un workflow fonctionnel, que tu peux copier-coller et adapter. Il se déclenche à chaque PR ouverte ou mise à jour, analyse le diff avec Claude Code, et poste le résultat en commentaire.

Le SDK TypeScript

Pour les cas où la ligne de commande ne suffit pas — quand tu as besoin de logique conditionnelle, de multi-turn (plusieurs échanges successifs), ou d'intégration dans une application — Anthropic fournit un SDK TypeScript dédié.

Le package s'appelle @anthropic-ai/claude-code. Il expose une fonction principale qui retourne des messages structurés, pas du texte brut.

import { claude } from "@anthropic-ai/claude-code";

// Appel simple
const messages = await claude({
  prompt: "Analyse ce fichier et identifie les problèmes",
  options: {
    allowedTools: ["Read", "Grep", "Glob"],
    maxTurns: 5
  }
});

// Chaque message a un type et du contenu
for (const msg of messages) {
  if (msg.type === "result") {
    console.log("Résultat:", msg.result);
    console.log("Coût:", msg.cost_usd);
  }
}

Le SDK te donne un contrôle fin que la ligne de commande n'offre pas. Tu peux enchaîner des appels, conditionner la suite en fonction du résultat, et surtout reprendre une conversation existante grâce au multi-turn.

Multi-turn avec --resume et --session-id

Le mode headless supporte les conversations à plusieurs tours. À chaque appel, Claude Code retourne un session_id. Tu peux le réutiliser pour continuer la conversation :

# Premier appel — analyse initiale
RESULT=$(claude -p "analyse les tests de ce projet" --output-format json)
SESSION_ID=$(echo $RESULT | jq -r '.session_id')

# Deuxième appel — on continue la conversation
claude -p "maintenant génère les tests manquants" \
  --resume \
  --session-id $SESSION_ID \
  --output-format json

Le deuxième appel a accès à tout le contexte du premier. Claude Code se souvient de son analyse et peut agir en conséquence. C'est indispensable pour les workflows en plusieurs étapes : analyser d'abord, puis corriger, puis vérifier.

En TypeScript avec le SDK, c'est encore plus élégant : tu passes le sessionId du premier appel dans les options du deuxième.

5 cas d'usage en CI/CD

Le mode headless ouvre des possibilités concrètes pour automatiser des tâches que personne n'a envie de faire manuellement. Voici les cinq cas d'usage les plus impactants.

1. Code review automatique sur chaque PR

On l'a vu avec le workflow GitHub Actions. À chaque pull request, Claude Code analyse le diff, identifie les problèmes, et poste un commentaire. Ce n'est pas un remplacement du code review humain — c'est un premier filtre. Les bugs évidents, les failles de sécurité basiques, le code mort, les imports inutilisés : tout ça est détecté automatiquement avant qu'un humain ne regarde la PR. Ça fait gagner un temps considérable, surtout dans les équipes où les PR s'accumulent.

2. Génération de tests

Tu pushes un nouveau fichier sans tests ? Claude Code détecte les fichiers modifiés sans couverture de tests, génère les tests correspondants, et les commit directement sur la branche. Le prompt type :

git diff --name-only HEAD~1 | claude -p \
  "Pour chaque fichier modifié, vérifie s'il existe un test correspondant. \
  Si non, génère un test unitaire pertinent." \
  --allowedTools "Read,Write,Glob,Grep"

Attention : ici tu donnes accès à l'outil Write (écriture de fichiers). C'est voulu, puisque Claude Code doit pouvoir créer les fichiers de tests. Mais assure-toi que le workflow tourne sur une branche dédiée, pas directement sur main.

3. Documentation automatique

Chaque merge sur main déclenche Claude Code pour mettre à jour la documentation. Il détecte les fonctions modifiées, vérifie si la documentation est encore à jour, et génère les mises à jour nécessaires. Plus jamais de documentation obsolète qui traîne pendant des mois.

4. Assistance à la migration

Tu migres une librairie de la v2 à la v3 ? Tu peux lancer Claude Code en headless sur chaque fichier impacté pour appliquer les changements nécessaires. C'est du batch processing (traitement par lot) : un script qui itère sur tous les fichiers et envoie chacun à Claude Code avec le prompt de migration. Ce qui prendrait des heures manuellement est fait en quelques minutes.

5. Refactoring guidé

Tu veux appliquer un pattern de refactoring (restructuration du code sans changer son comportement) à tout un projet ? Par exemple, remplacer tous les callbacks par des async/await, ou migrer tous les composants de classes vers des composants fonctionnels. Claude Code en headless peut traiter chaque fichier de manière indépendante et parallèle.

Pour des cas d'usage plus avancés impliquant des sub-agents, tu peux combiner le mode headless avec la délégation de tâches. Un agent principal qui orchestre, des sub-agents qui exécutent — le tout dans un pipeline CI/CD.

Sécurité et bonnes pratiques

Lancer une IA dans un pipeline automatisé, ça nécessite de la rigueur sur la sécurité. Voici les règles à suivre.

Gestion des clés API

Jamais de clé API en dur dans le code ou dans un fichier YAML. Toujours utiliser les secrets du CI (GitHub Secrets, GitLab CI Variables, etc.). La variable d'environnement ANTHROPIC_API_KEY est la méthode standard. Si tu utilises AWS Bedrock ou Google Vertex comme provider, utilise CLAUDE_CODE_USE_BEDROCK ou CLAUDE_CODE_USE_VERTEX avec les credentials correspondantes.

Permissions restrictives

En CI/CD, utilise toujours --allowedTools pour limiter ce que Claude Code peut faire. Pour une review : lecture seule (Read, Grep, Glob). Pour de la génération : ajoute Write. N'accorde Bash que si c'est absolument nécessaire — et dans ce cas, --disallowedTools peut exclure des commandes spécifiques. Le flag --permission-mode ajoute une couche de contrôle supplémentaire.

Timeouts et limites

Un appel Claude Code en headless peut prendre du temps sur un gros codebase. Définis toujours un timeout dans ton workflow CI. Sur GitHub Actions, tu peux ajouter timeout-minutes: 10 au niveau du job. C'est du bon sens, mais ça évite un workflow qui tourne (et facture) indéfiniment en cas de problème.

Surveillance des coûts

Chaque appel headless en JSON retourne cost_usd. Log ce champ systématiquement. Mets des alertes si le coût d'un seul appel dépasse un seuil (par exemple 1$). Agrège les coûts sur une semaine/mois. Claude Code en CI/CD c'est puissant, mais sans surveillance, la facture peut grimper vite — surtout si chaque push sur chaque branche déclenche un appel.

Isolation

Chaque appel headless en CI/CD tourne dans un environnement frais (le runner GitHub Actions, par exemple). Il n'y a pas de persistance de session entre les runs. C'est une bonne chose pour la sécurité : pas de fuite de contexte d'un run à l'autre. Si tu as besoin de persistance (multi-turn sur plusieurs jobs), utilise le session_id explicitement et stocke-le comme artefact.

Pour approfondir la gestion des permissions, le guide sur les permissions et la sécurité couvre le sujet en détail. Et si tu travailles en équipe, le guide sur Claude Code en équipe et en entreprise aborde les aspects de gouvernance et de contrôle d'accès.

Meydeey

Architecte IA & Automatisation · Fondateur LE LABO IA · +25 000 abonnés YouTube