Claude Code GitLab CI/CD

​

Warum Claude Code mit GitLab verwenden?

• Sofortige MR-Erstellung: Beschreiben Sie, was Sie benötigen, und Claude schlägt einen vollständigen MR mit Änderungen und Erklärung vor
• Automatisierte Implementierung: Verwandeln Sie Probleme mit einem einzigen Befehl oder einer Erwähnung in funktionierenden Code
• Projektbewusst: Claude folgt Ihren CLAUDE.md-Richtlinien und vorhandenen Code-Mustern
• Einfaches Setup: Fügen Sie einen Job zu .gitlab-ci.yml und eine maskierte CI/CD-Variable hinzu
• Enterprise-ready: Wählen Sie Claude API, Amazon Bedrock oder Google Cloud’s Agent Platform, um Anforderungen an Datenresidenz und Beschaffung zu erfüllen
• Standardmäßig sicher: Läuft in Ihren GitLab-Runnern mit Ihrem Branch-Schutz und Genehmigungen

​

Wie es funktioniert

1. Ereignisgesteuerte Orchestrierung: GitLab lauscht auf Ihre gewählten Trigger (zum Beispiel ein Kommentar, der @claude in einem Problem, MR oder Review-Thread erwähnt). Der Job sammelt Kontext aus dem Thread und Repository, erstellt Prompts aus dieser Eingabe und führt Claude Code aus.
2. Provider-Abstraktion: Verwenden Sie den Provider, der zu Ihrer Umgebung passt:
   • Claude API (SaaS)
   • Amazon Bedrock (IAM-basierter Zugriff, regionsübergreifende Optionen)
   • Google Cloud’s Agent Platform (GCP-nativ, Workload Identity Federation)
3. Sandboxed-Ausführung: Jede Interaktion läuft in einem Container mit strikten Netzwerk- und Dateisystem-Regeln. Claude Code erzwingt Workspace-bezogene Berechtigungen, um Schreibvorgänge einzuschränken. Jede Änderung fließt durch einen MR, damit Reviewer den Diff sehen und Genehmigungen weiterhin gelten.

​

Was kann Claude tun?

• MRs aus Issue-Beschreibungen oder Kommentaren erstellen und aktualisieren
• Leistungsregressionen analysieren und Optimierungen vorschlagen
• Funktionen direkt in einem Branch implementieren und dann eine MR öffnen
• Fehler und Regressionen beheben, die durch Tests oder Kommentare identifiziert wurden
• Auf Folgekommen antworten, um angeforderte Änderungen zu iterieren

​

Einrichtung

​

Schnelle Einrichtung

1. Fügen Sie eine maskierte CI/CD-Variable hinzu
   • Gehen Sie zu Einstellungen → CI/CD → Variablen
   • Fügen Sie ANTHROPIC_API_KEY hinzu (maskiert, bei Bedarf geschützt)
2. Fügen Sie einen Claude-Job zu .gitlab-ci.yml hinzu

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Passen Sie die Regeln an, um festzulegen, wie Sie den Job auslösen möchten:
  # - manuelle Ausführungen
  # - Merge-Request-Ereignisse
  # - Web-/API-Trigger, wenn ein Kommentar „@claude" enthält
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_STRATEGY: fetch
  before_script:
    - apk update
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
    # Das Installationsprogramm platziert Claude in ~/.local/bin, das in diesem Image nicht auf PATH ist
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    # Optional: Starten Sie einen GitLab-MCP-Server, wenn Ihr Setup einen bereitstellt
    - /bin/gitlab-mcp-server || true
    # Verwenden Sie AI_FLOW_*-Variablen beim Aufrufen über Web-/API-Trigger mit Kontext-Payloads
    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug

​

Manuelle Einrichtung (empfohlen für Produktion)

1. Konfigurieren Sie den Provider-Zugriff:
   • Claude API: Erstellen und speichern Sie ANTHROPIC_API_KEY als maskierte CI/CD-Variable
   • Amazon Bedrock: Konfigurieren Sie GitLab → AWS OIDC und erstellen Sie eine IAM-Rolle für Amazon Bedrock
   • Google Cloud’s Agent Platform: Konfigurieren Sie Workload Identity Federation für GitLab → GCP
2. Fügen Sie Projektanmeldedaten für GitLab-API-Operationen hinzu:
   • Verwenden Sie CI_JOB_TOKEN standardmäßig, oder erstellen Sie ein Project Access Token mit api-Bereich
   • Speichern Sie als GITLAB_ACCESS_TOKEN (maskiert), wenn Sie ein PAT verwenden
3. Fügen Sie den Claude-Job zu .gitlab-ci.yml hinzu: Verwenden Sie den Schnelle Einrichtung-Job für die Claude API, oder einen Provider-Job aus Konfigurationsbeispiele
4. (Optional) Aktivieren Sie Mention-gesteuerte Trigger:
   • Fügen Sie einen Projekt-Webhook für „Kommentare (Notizen)” zu Ihrem Event-Listener hinzu (falls Sie einen verwenden)
   • Lassen Sie den Listener die Pipeline-Trigger-API mit Variablen wie AI_FLOW_INPUT und AI_FLOW_CONTEXT aufrufen, wenn ein Kommentar @claude enthält

​

Beispiele für Anwendungsfälle

​

Probleme in Merge Requests umwandeln

@claude implement this feature based on the issue description

​

Implementierungshilfe erhalten

@claude suggest a concrete approach to cache the results of this API call

​

Fehler schnell beheben

@claude fix the TypeError in the user dashboard component

​

Verwendung mit Amazon Bedrock und Google Cloud

​

Konfigurationsbeispiele

​

Amazon Bedrock-Auftragsbeispiel (OIDC)

• Amazon Bedrock aktiviert mit Zugriff auf Ihr(e) gewählte(s) Claude-Modell(e)
• GitLab OIDC in AWS konfiguriert mit einer Rolle, die Ihr GitLab-Projekt und Refs vertraut
• IAM-Rolle mit Amazon Bedrock-Berechtigungen (Least-Privilege empfohlen)

• AWS_ROLE_TO_ASSUME: ARN der IAM-Rolle für Amazon Bedrock-Zugriff
• AWS_REGION: Amazon Bedrock-Region (zum Beispiel us-west-2)

stages:
  - ai

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apk add --no-cache bash curl jq git aws-cli
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Exchange the job's OIDC token for AWS credentials
    - export AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/oidc_token"
    - printf "%s" "$GITLAB_OIDC_TOKEN" > "$AWS_WEB_IDENTITY_TOKEN_FILE"
    - >
      aws sts assume-role-with-web-identity
      --role-arn "$AWS_ROLE_TO_ASSUME"
      --role-session-name "gitlab-claude-$(date +%s)"
      --web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE"
      --duration-seconds 3600 > /tmp/aws_creds.json
    - export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
    - export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
    - export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Implement the requested changes and open an MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"
    CLAUDE_CODE_USE_BEDROCK: "1"

​

Agent Platform-Auftragsbeispiel (Workload Identity Federation)

• Google Cloud’s Agent Platform API in Ihrem GCP-Projekt aktiviert
• Workload Identity Federation konfiguriert, um GitLab OIDC zu vertrauen
• Ein Dienstkonto mit Google Cloud’s Agent Platform-Berechtigungen

• GCP_WORKLOAD_IDENTITY_PROVIDER: Anbieter-Ressourcenname ohne das //iam.googleapis.com/-Präfix, wie projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
• GCP_SERVICE_ACCOUNT: E-Mail des Dienstkontos
• GCP_PROJECT_ID: Google Cloud-Projekt-ID
• CLOUD_ML_REGION: Google Cloud’s Agent Platform-Region (zum Beispiel us-east5)

stages:
  - ai

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apt-get update && apt-get install -y git && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Write the job's OIDC token where credential_source expects it
    - printf "%s" "$GITLAB_OIDC_TOKEN" > /tmp/oidc_token
    # Write the WIF credential configuration to a file (no downloaded keys)
    - |
      cat > /tmp/cred.json <<EOF
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "/tmp/oidc_token"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken"
      }
      EOF
    # Expose the credentials to Claude Code via Application Default Credentials
    - export GOOGLE_APPLICATION_CREDENTIALS=/tmp/cred.json
    # Authenticate the gcloud CLI with the same credential configuration
    - gcloud auth login --cred-file=/tmp/cred.json
    - gcloud config set project "$GCP_PROJECT_ID"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}"
      claude
      -p "${AI_FLOW_INPUT:-'Review and update code as requested'}"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"
    CLAUDE_CODE_USE_VERTEX: "1"
    ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"

​

Best Practices

​

CLAUDE.md-Konfiguration

​

Sicherheitsaspekte

• Fügen Sie ANTHROPIC_API_KEY als maskierte Variable hinzu (und schützen Sie sie bei Bedarf)
• Verwenden Sie wo möglich anbieterspezifisches OIDC (keine langlebigen Schlüssel)
• Begrenzen Sie Job-Berechtigungen und Netzwerk-Egress
• Überprüfen Sie Claudes MRs wie jeden anderen Beitrag

​

Leistungsoptimierung

• Halten Sie CLAUDE.md fokussiert und prägnant
• Geben Sie klare Issue-/MR-Beschreibungen an, um Iterationen zu reduzieren
• Cachen Sie npm und Paketinstallationen in Runnern, wo möglich

​

CI-Kosten

• GitLab Runner-Zeit:
  • Claude läuft auf Ihren GitLab-Runnern und verbraucht Compute-Minuten
  • Weitere Informationen finden Sie in der Runner-Abrechnung Ihres GitLab-Plans
• API-Kosten:
  • Jede Claude-Interaktion verbraucht Token basierend auf der Größe von Prompt und Antwort
  • Die Token-Nutzung variiert je nach Aufgabenkomplexität und Codebase-Größe
  • Weitere Informationen finden Sie unter Anthropic-Preisgestaltung
• Tipps zur Kostenoptimierung:
  • Verwenden Sie spezifische @claude-Befehle, um unnötige Durchläufe zu reduzieren
  • Legen Sie angemessene --max-turns- und Job-timeout-Werte fest
  • Begrenzen Sie die Parallelität, um parallele Ausführungen zu kontrollieren

​

Fehlerbehebung

​

Claude antwortet nicht auf @claude-Befehle

• Überprüfen Sie, dass Ihre Pipeline ausgelöst wird (manuell, MR-Ereignis oder über einen Note-Ereignis-Listener/Webhook)
• Stellen Sie sicher, dass Ihre ANTHROPIC_API_KEY oder Cloud-Provider-Variablen vorhanden sind
• Überprüfen Sie, dass der Kommentar @claude enthält (nicht /claude) und dass Ihr Mention-Trigger konfiguriert ist

​

Job kann keine Kommentare schreiben oder MRs öffnen

• Stellen Sie sicher, dass CI_JOB_TOKEN ausreichende Berechtigungen für das Projekt hat, oder verwenden Sie ein Project Access Token mit api-Bereich
• Überprüfen Sie, dass das mcp__gitlab-Tool in --allowedTools aktiviert ist
• Bestätigen Sie, dass der Job im Kontext des MR ausgeführt wird oder über AI_FLOW_*-Variablen genügend Kontext hat

​

Authentifizierungsfehler

• Für Claude API: Bestätigen Sie, dass ANTHROPIC_API_KEY gültig und nicht abgelaufen ist
• Für Amazon Bedrock oder Google Cloud’s Agent Platform: Überprüfen Sie die OIDC/WIF-Konfiguration, Rollenidentitätswechsel und Geheimnisnamen; bestätigen Sie Regionen- und Modellverfügbarkeit

​

Erweiterte Konfiguration

​

Häufige Parameter und Variablen

• -p: Anweisungen inline bereitstellen, zum Beispiel claude -p "Review this MR"
• --max-turns: Begrenzen Sie die Anzahl der Hin- und Herbewegungen
• timeout: Begrenzen Sie die gesamte Job-Ausführungszeit mit GitLabs Job-Level-Schlüsselwort timeout, zum Beispiel timeout: 30m
• ANTHROPIC_API_KEY: erforderlich für die Claude API (nicht verwendet für Amazon Bedrock oder Google Cloud’s Agent Platform)
• Anbieter-spezifische Umgebung: AWS_REGION, Projekt-/Regionsvariablen für Google Cloud’s Agent Platform

​

Anpassung des Verhaltens von Claude

1. CLAUDE.md: Definieren Sie Codierungsstandards, Sicherheitsanforderungen und Projektkonventionen. Claude liest dies während der Ausführungen und befolgt Ihre Regeln.
2. Benutzerdefinierte Prompts: Übergeben Sie aufgabenspezifische Anweisungen über -p im Job. Verwenden Sie unterschiedliche Prompts für verschiedene Jobs (zum Beispiel Review, Implementierung, Umgestaltung).