CI/CD & Headless Mode
Level 3 | 40 Minuten
Claude Code in GitHub Actions, GitLab CI und automatisierten Pipelines einsetzen
Lernziele
- Headless Mode (-p Flag) für Automation beherrschen
- GitHub Actions mit Claude Code aufsetzen
- GitLab CI/CD Integration konfigurieren
- Automatische Code Reviews implementieren
- Sichere Pipeline-Konfiguration erstellen
Headless Mode – Claude ohne Terminal
Der Headless Mode (auch Print Mode genannt) ist der Schlüssel zur Integration von Claude Code in automatisierte Workflows. Mit dem -p Flag wird Claude Code von einem interaktiven Chat-Tool zu einem programmierbaren Baustein den du in Skripte, Pipelines und Cron-Jobs einbinden kannst. Das Grundprinzip ist einfach: 'claude -p "Dein Prompt hier"' sendet den Prompt an Claude, wartet auf die Antwort, gibt sie auf stdout aus und beendet sich. Kein Dialog, keine Rückfragen, kein Warten auf Nutzer-Input. Reines Input-Output wie bei jedem anderen Unix-Tool. Der Headless Mode unterstützt alle Standard-Unix-Patterns: Piping ('cat file.js | claude -p "Erkläre diesen Code"'), Redirection ('claude -p "Generiere eine .gitignore" > .gitignore'), Command Substitution ('BUGS=$(claude -p "Finde Bugs in @src/app.ts")'). Für maschinelle Verarbeitung nutze --output-format json. Statt Freitext bekommst du ein JSON-Objekt mit Feldern wie: result (die eigentliche Antwort), usage (Token-Verbrauch), cost (Kosten in USD), model (verwendetes Modell) und duration_ms (Laufzeit). Das kannst du mit jq, Python oder JavaScript weiterverarbeiten. Kritische Flags für den automatisierten Betrieb: --max-turns begrenzt die Iterationen (verhindert Endlosschleifen und Kostenexplosion), --max-budget-usd setzt ein hartes Kosten-Limit, --allowedTools beschränkt die erlaubten Aktionen, und --model wählt das optimale Modell für die Aufgabe. Der Headless Mode ist die Brücke zwischen Claude Code und dem Rest deiner Automatisierungs-Infrastruktur: GitHub Actions, GitLab CI, Jenkins, Cron-Jobs, Monitoring-Skripte — alles was einen Shell-Befehl ausführen kann, kann Claude Code nutzen.
# Grundlagen: Der -p Flag
claude -p "Erkläre was dieser Code tut" < file.js
# → Claude analysiert die Datei und gibt Erklärung aus
# Mit Datei-Kontext:
claude -p "Finde Bugs in @src/api/auth.ts"
# → Claude liest die Datei und gibt Bugfixes aus
# Stdin pipen:
cat src/utils.ts | claude -p "Finde potenzielle Bugs"
git diff HEAD~1 | claude -p "Beschreibe diese Änderungen"
npm test 2>&1 | claude -p "Erkläre die fehlgeschlagenen Tests"
# Output-Formate:
claude -p "Analysiere package.json" --output-format text # Standard
claude -p "Analysiere package.json" --output-format json # Strukturiert
claude -p "Analysiere package.json" --output-format stream-json
# Iterationen begrenzen (wichtig für CI!):
claude -p "Fix lint errors" --max-turns 5
# → Claude stoppt nach maximal 5 Aktionsschritten
# → Verhindert Endlosschleifen in der Pipeline
# Tools einschränken (Sicherheit in CI):
claude -p "Review code" --allowedTools "Read,Bash(git diff)"
# → Claude kann NUR lesen und git diff ausführen
# → Kein Schreibzugriff in der PipelineJSON Output für maschinelle Verarbeitung
Im Headless Mode kann Claude die Ergebnisse als strukturiertes JSON ausgeben statt als Freitext. Das ist ideal für die Weiterverarbeitung in Skripten, Pipelines und Dashboards — du kannst Token-Verbrauch, Kosten und Ergebnisse programmatisch auswerten und in dein Monitoring integrieren. Die Aktivierung ist einfach: 'claude -p "Dein Prompt" --output-format json'. Statt einer lesbaren Textantwort bekommst du ein JSON-Objekt mit definierten Feldern: result (die eigentliche Antwort), usage (Input- und Output-Tokens), cost_usd (Kosten), model (verwendetes Modell), duration_ms (Laufzeit). Für Skripte ist das extrem wertvoll: Du kannst das JSON mit jq parsen, mit Python verarbeiten, oder in eine Datenbank schreiben. Zum Beispiel: 'claude -p "Review" --output-format json | jq .cost_usd' gibt dir nur die Kosten. Oder: Schreibe die Ergebnisse in eine CSV für monatliche Auswertung. In CI/CD-Pipelines nutzt du JSON Output für Conditional Logic: Wenn der Review Schweregrad 'critical' enthält → Pipeline fehlschlagen lassen. Wenn die Kosten über einem Threshold liegen → Warnung senden. Wenn keine Findings → Auto-Approve. Das JSON-Format ist stabil und versioniert — du kannst dich darauf verlassen dass die Feldnamen und Struktur über Updates hinweg konsistent bleiben. Das ist wichtig für langfristige Automatisierung. Ein Praxis-Tipp: Kombiniere --output-format json mit --output-format stream-json für Echtzeit-Verarbeitung. Statt auf die komplette Antwort zu warten, bekommst du JSON-Chunks die du progressiv verarbeiten kannst — ideal für Live-Dashboards und Progress-Anzeigen.
# JSON Output aktivieren:
claude -p "Finde alle TODO-Kommentare" --output-format json
# Output:
# {
# "result": "Gefundene TODOs:
1. src/app.ts:42 - TODO: Error handling
...",
# "cost": { "input_tokens": 5230, "output_tokens": 1450 },
# "duration_ms": 3200,
# "model": "claude-sonnet-4.5"
# }
# In Scripts verarbeiten:
RESULT=$(claude -p "Analysiere Code-Qualität" --output-format json)
SCORE=$(echo $RESULT | jq -r '.result' | grep -o 'Score: [0-9]*' | head -1)
if [ "$SCORE" -lt 70 ]; then
echo "Code-Qualität zu niedrig: $SCORE"
exit 1
fi
# Stream-JSON für Echtzeit-Verarbeitung:
claude -p "Generiere Tests" --output-format stream-json | while read line; do
echo "Claude: $line"
doneGitHub Actions Integration
Die Integration von Claude Code in GitHub Actions ermöglicht automatisierte Code-Reviews, Test-Generierung und Quality-Checks bei jedem Pull Request. Es gibt zwei Wege: Die offizielle GitHub Action für schnellen Einstieg, oder Custom Workflows mit dem Headless Mode für maximale Flexibilität. Die offizielle Action (anthropics/claude-code-action) ist in 5 Minuten eingerichtet: YAML-Workflow-Datei erstellen, ANTHROPIC_API_KEY als Repository-Secret hinterlegen, und die Action im PR-Trigger konfigurieren. Bei jedem neuen PR analysiert Claude den Diff und postet ein detailliertes Review als Kommentar. Für Custom Workflows nutzt du den Headless Mode: Im YAML-Workflow installierst du Claude Code, setzt die Umgebungsvariablen und führst 'claude -p' mit deinem spezifischen Prompt aus. Das gibt dir volle Kontrolle: Welches Modell, welche Tools, welches Output-Format, welche Checks. Typische Workflow-Konfiguration: Trigger bei PR-Erstellung oder -Update. Checkout des Codes. Claude Code Installation. Ausführung mit --max-turns 5 und --model sonnet. JSON-Output in eine Variable. Parsing und Posting als PR-Kommentar oder Status-Check. Bewährte Praxis für Teams: Nutze separate Workflows für verschiedene Check-Typen: Ein Workflow für Code-Review, einer für Security-Audit, einer für Test-Coverage. So kannst du die Kosten und Laufzeiten pro Check optimieren. Kosten-Management: Nutze if-Conditions im Workflow um Claude nur bei relevanten Änderungen zu triggern: 'if: contains(github.event.pull_request.changed_files, 'src/') — nur bei Source-Änderungen. Docs-Updates brauchen kein Claude-Review. Ein Sicherheitshinweis: Nutze NIEMALS --dangerously-skip-permissions in öffentlichen Repositories. In privaten Repos: Nur in Kombination mit Container-Isolation und minimalen Tool-Berechtigungen.
# .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
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Get changed files
id: changes
run: |
echo "files=$(git diff --name-only origin/main...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT
- name: Claude Code Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff origin/main...HEAD | claude -p \
"Reviewe diese Code-Änderungen. Prüfe auf:
1. Bugs und Sicherheitslücken
2. Performance-Probleme
3. Best Practice Verstöße
4. Fehlende Error-Handling
Gib eine Zusammenfassung als Markdown." \
--output-format text \
--max-turns 3 \
--allowedTools "Read" \
> 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({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '## 🤖 Claude Code Review\n\n' + review
});Weitere GitHub Actions Workflows
Neben dem Standard-Code-Review gibt es zahlreiche weitere Einsatzmöglichkeiten für Claude Code in GitHub Actions. Hier sind die nützlichsten Workflows die über ein einfaches Review hinausgehen und echten Mehrwert für dein Team liefern. Automatische Test-Generierung: Wenn neue Dateien in einem PR hinzugefügt werden, generiert Claude automatisch Test-Dateien. Der Workflow identifiziert neue .ts/.tsx Dateien im Diff, lässt Claude Tests generieren, und erstellt einen separaten Commit mit den Tests. Security-Audit: Ein regelmäßiger (z.B. wöchentlicher) Workflow der die gesamte Codebase auf Sicherheitsprobleme scannt. Claude analysiert den Code auf OWASP Top 10, prüft Dependencies auf bekannte Schwachstellen, und erstellt ein Issue mit den Findings. Release-Note-Generierung: Bei jedem Release-Tag analysiert Claude die Commits seit dem letzten Release, kategorisiert sie (Features, Bug Fixes, Verbesserungen) und generiert formatierte Release Notes. Dependency-Update-Review: Wenn Dependabot oder Renovate einen PR erstellt, analysiert Claude die Changelog-Einträge der aktualisierten Packages und bewertet das Risiko. Niedrig-Risiko-Updates können automatisch gemergt werden. Code-Dokumentation: Bei jedem PR prüft Claude ob neue oder geänderte Funktionen dokumentiert sind. Fehlende Dokumentation wird als PR-Kommentar angemahnt oder automatisch generiert. Für jeden dieser Workflows gilt: --max-turns begrenzen, --allowedTools einschränken, Kosten-Limit setzen. Ein unkontrollierter Agent in der Pipeline kann teuer werden.
# Auto-Fix Lint Errors
name: Claude Auto-Fix
on:
push:
branches: [develop]
jobs:
auto-fix:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g @anthropic-ai/claude-code
- name: Fix Lint Errors
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npm run lint 2>&1 | claude -p \
"Behebe alle Lint-Fehler in den betroffenen Dateien." \
--max-turns 10 \
--sandbox
- name: Commit Fixes
run: |
git config user.name "Claude Code Bot"
git config user.email "claude@bot.com"
git add -A
git diff --staged --quiet || git commit -m "fix: auto-fix lint errors via Claude Code"
git push# Automatische Issue-Bearbeitung
name: Claude Issue Handler
on:
issues:
types: [labeled]
jobs:
implement:
if: github.event.label.name == 'claude-implement'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g @anthropic-ai/claude-code
- name: Implement Feature
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
ISSUE_BODY="${{ github.event.issue.body }}"
claude -p "Implementiere folgendes Feature basierend
auf dieser Issue-Beschreibung:
$ISSUE_BODY
Erstelle einen neuen Branch, implementiere das Feature,
und erstelle einen Draft PR." \
--max-turns 20 \
--sandboxGitLab CI/CD Integration
Claude Code lässt sich auch in GitLab CI/CD-Pipelines integrieren. Die Konfiguration erfolgt in der .gitlab-ci.yml und ist konzeptionell ähnlich zur GitHub Actions Integration — mit einigen GitLab-spezifischen Besonderheiten. Der grundlegende Aufbau: Du definierst einen Pipeline-Job der Claude Code installiert, authentifiziert und im Headless Mode ausführt. Die Ergebnisse kannst du als GitLab-Kommentar auf dem Merge Request posten oder als Pipeline-Artefakt speichern. Die Authentifizierung erfolgt über eine CI/CD-Variable: Speichere den ANTHROPIC_API_KEY als geschützte (protected) und maskierte (masked) Variable in den GitLab CI/CD Einstellungen. So ist der Key im Pipeline-Log nicht sichtbar. Für MR-Comments nutzt du die GitLab API: 'curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" --data "body=$REVIEW" "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"'. Das postet Claudes Review als Kommentar auf dem Merge Request. GitLab-spezifische Vorteile: GitLab CI/CD Runner laufen oft self-hosted — du hast volle Kontrolle über die Ausführungsumgebung. Das macht Sandboxing einfacher und gibt dir mehr Optionen für Netzwerk-Isolation. Für Teams die sowohl GitHub als auch GitLab nutzen: Erstelle ein wiederverwendbares Shell-Skript das die Claude Code Integration abstrahiert. Das Skript wird von beiden Plattformen aufgerufen und du musst die Logik nur einmal pflegen. Kosten-Kontrolle in GitLab: Nutze GitLab CI/CD Rules um Pipelines nur bei relevanten Änderungen zu triggern. Und: Setze Resource-Limits auf den Runner um zu verhindern dass ein hängengebliebener Agent unbegrenzt Tokens verbraucht.
# .gitlab-ci.yml
stages:
- review
- test
- fix
claude-review:
stage: review
image: node:20
only:
- merge_requests
before_script:
- npm install -g @anthropic-ai/claude-code
script:
- |
git diff origin/main...HEAD | claude -p \
"Reviewe diese Änderungen für den Merge Request.
Fokus: Sicherheit, Performance, Code-Qualität." \
--output-format text \
--max-turns 3 > review.md
- cat review.md
artifacts:
paths:
- review.md
claude-test-gen:
stage: test
image: node:20
only:
- merge_requests
before_script:
- npm install -g @anthropic-ai/claude-code
- npm ci
script:
- |
CHANGED=$(git diff --name-only origin/main...HEAD | grep '.ts