Claude Code headless im CI/CD

Headless Mode lässt Claude Code wie jedes andere CLI-Tool laufen: einen Prompt als Argument übergeben, Output über stdout zurückbekommen. Genau das, was du brauchst, um Claude Code in GitHub Actions, GitLab CI, Jenkins oder einem Cron-Job einzusetzen.

Für wen ist das?

Für Entwickler und DevOps-Teams, die Claude Code aus dem interaktiven Terminal heraus in die Automatisierung tragen wollen – von PR-Reviews über Doku-Generation bis zu Sicherheitsscans.

Was lernst du?

• Wie claude -p funktioniert und wann du es einsetzen solltest
• Wie du Tool-Zugriff im non-interaktiven Modus absicherst (--allowedTools)
• Wie du JSON-Output für nachgelagerte Pipeline-Schritte nutzt
• Wie du Claude Code in GitHub Actions integrierst (komplettes Beispiel)
• Welche Kosten-Regelung ab Juni 2026 gilt

Wann nutzen?

• PR-Auto-Reviews: Jeder neue PR bekommt einen Claude-Review-Kommentar
• Doku-Aktualisierung: Nightly Job hält die README aktuell, wenn sich die API ändert
• Test-Triage: Failed-CI-Runs werden automatisch nach Root-Cause gruppiert
• Security-Scan: Wöchentliches Audit von Dependencies und Secrets
• Migration-Checks: Vor jedem Deploy prüft Claude die Migrations-Diff

Wann nicht?

• Bei explorativer Arbeit ohne klares Ziel
• Wenn du mehrstufige Rückfragen brauchst – non-interaktiv erlaubt keine Konversation
• Bei sicherheitskritischen Schreibaktionen ohne Review – Headless darf nur, was du explizit erlaubst

Der -p-Flag – Das Herzstück

# Einfacher Aufruf:
claude -p "Find and fix the bug in auth.py" \
  --allowedTools "Read,Edit,Bash"

# JSON-Output für Pipelines:
claude -p "Review changes since main" \
  --allowedTools "Read,Bash" \
  --output-format json

# Stream-JSON (live-parsierbar):
claude -p "Refactor user.ts" \
  --output-format stream-json

-p (für „print”) deaktiviert alle User-Interaktion: kein Tab-Complete, keine Confirmations, kein Folge-Prompt. Claude liest stdin und schreibt nach stdout – wie grep oder sed.

Tool-Zugriff absichern

Im interaktiven Modus fragt Claude vor heiklen Aktionen nach. Headless macht das nicht – du musst explizit erlauben:

# Nur Lesen + Test ausführen:
claude -p "Run tests and explain failures" \
  --allowedTools "Read,Grep,Bash(npm test:*)"

# Auch Edits erlauben:
claude -p "Fix the failing test" \
  --allowedTools "Read,Edit,Grep,Bash(npm test:*)"

# `--bare` ignoriert lokale Konfiguration komplett (empfohlen für CI):
claude -p "Audit dependencies" \
  --allowedTools "Read,Bash(npm audit:*)" \
  --bare

Bash-Befehle lassen sich mit Glob-Pattern einschränken: Bash(npm test:*) erlaubt npm test, npm test --watch, aber nicht npm run deploy.

Output-Formate

# JSON-Output direkt weiterverarbeiten:
claude -p "Summarize git log since v1.2" --output-format json \
  | jq -r '.result.text' > CHANGELOG.md

GitHub Actions: Komplettes Beispiel

PR-Auto-Review-Workflow, der auf jeden neuen PR Claude einen Kommentar mit Review-Findings posten lässt:

# .github/workflows/claude-pr-review.yml
name: Claude PR 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 "Review the changes in this PR. Focus on logic bugs, missing tests, and security issues. Be concise — max 5 findings." \
            --allowedTools "Read,Grep,Bash(git diff:*,git log:*)" \
            --bare \
            --output-format json \
            > review.json

      - name: Post review comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          jq -r '.result.text' review.json \
            | gh pr comment ${{ github.event.pull_request.number }} --body-file -

Headless-Run aufbauen – Schritt für Schritt

Typische Fehler

• Zu lockere Tool-Whitelist: --allowedTools "*" ist ein Sicherheitsrisiko in CI. Immer enumerieren, was wirklich gebraucht wird.
• Vergessen, --bare zu setzen: In CI lokale Settings durchzulassen, macht Builds unreproduzierbar – und manchmal unsicher (falls jemand lokal experimentelle Hooks hatte).
• Kein Längen-Limit im Prompt: Headless-Runs ohne Längen-Vorgabe können seitenweise produzieren. Bei PR-Kommentaren: „Be concise – max 5 findings”.
• Idempotenz vergessen: Ohne Schutz kommentiert jeder Re-Run nochmal. Marker-String im Kommentar prüfen oder bestehenden Kommentar updaten.
• API-Key leaken: Im Workflow als Secret, nie als Plain-Text. Echo des Keys in Logs vermeiden (set +x).
• Kosten unterschätzen: Ab 15. Juni 2026 zieht claude -p aus einem getrennten Agent-SDK-Credit. Bei viel Volumen API-Abrechnung erwägen.

Mini-Übung

Baue einen Mini-Headless-Run lokal – Doku-Aktualisierung:

1. In einem kleinen Repo: claude -p "Read README.md and src/. List 3 sections of the README that are out of date." --allowedTools "Read,Grep" --bare --output-format text
2. Output prüfen – bekommst du eine knappe Liste?
3. Variante mit JSON: --output-format json → jq auf .result.text
4. Längen-Limit einbauen: „Max 80 words.” – wird der Output kompakter?
5. Wenn das stabil läuft, hast du die Grundlage für jeden CI-Workflow

Nächster Schritt

Du weißt jetzt, wie Claude Code als CLI-Tool in Pipelines läuft. Als Nächstes: Wenn Claude lokale Aktionen am Rechner ausführen soll (Browser steuern, Tabellenkalkulation öffnen), brauchst du den Guide Computer Use sicher einsetzen – eine andere Art von Headless, mit ganz eigenen Sicherheitsfragen.