Claude Code GitLab CI/CD

​

Perché usare Claude Code con GitLab?

• Creazione istantanea di MR: Descrivi quello di cui hai bisogno e Claude propone un MR completo con modifiche e spiegazione
• Implementazione automatizzata: Trasforma i problemi in codice funzionante con un singolo comando o menzione
• Consapevolezza del progetto: Claude segue le tue linee guida CLAUDE.md e i modelli di codice esistenti
• Configurazione semplice: Aggiungi un lavoro a .gitlab-ci.yml e una variabile CI/CD mascherata
• Pronto per l’azienda: Scegli Claude API, AWS Bedrock o Google Vertex AI per soddisfare le esigenze di residenza dei dati e di approvvigionamento
• Sicuro per impostazione predefinita: Viene eseguito nei tuoi runner GitLab con la protezione dei rami e le approvazioni

​

Come funziona

1. Orchestrazione basata su eventi: GitLab ascolta i trigger scelti (ad esempio, un commento che menziona @claude in un problema, MR o thread di revisione). Il lavoro raccoglie il contesto dal thread e dal repository, costruisce prompt da tale input ed esegue Claude Code.
2. Astrazione del provider: Utilizza il provider che si adatta al tuo ambiente:
   • Claude API (SaaS)
   • AWS Bedrock (accesso basato su IAM, opzioni multi-regione)
   • Google Vertex AI (nativo GCP, Workload Identity Federation)
3. Esecuzione in sandbox: Ogni interazione viene eseguita in un contenitore con regole rigorose di rete e file system. Claude Code applica autorizzazioni con ambito workspace per limitare le scritture. Ogni modifica passa attraverso un MR in modo che i revisori vedano il diff e le approvazioni si applichino ancora.

​

Cosa può fare Claude?

• Creare e aggiornare MR da descrizioni di problemi o commenti
• Analizzare regressioni di prestazioni e proporre ottimizzazioni
• Implementare funzionalità direttamente in un ramo, quindi aprire un MR
• Correggere bug e regressioni identificati da test o commenti
• Rispondere ai commenti di follow-up per iterare sulle modifiche richieste

​

Configurazione

​

Configurazione rapida

1. Aggiungi una variabile CI/CD mascherata
   • Vai a Impostazioni → CI/CD → Variabili
   • Aggiungi ANTHROPIC_API_KEY (mascherata, protetta secondo necessità)
2. Aggiungi un lavoro Claude a .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Regola le regole per adattarsi a come desideri attivare il lavoro:
  # - esecuzioni manuali
  # - eventi di merge request
  # - trigger web/API quando un commento contiene '@claude'
  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
    - npm install -g @anthropic-ai/claude-code
  script:
    # Facoltativo: avvia un server GitLab MCP se la tua configurazione ne fornisce uno
    - /bin/gitlab-mcp-server || true
    # Utilizza variabili AI_FLOW_* quando richiami tramite trigger web/API con payload di contesto
    - 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

​

Configurazione manuale (consigliata per la produzione)

1. Configura l’accesso al provider:
   • Claude API: Crea e archivia ANTHROPIC_API_KEY come variabile CI/CD mascherata
   • AWS Bedrock: Configura GitLab → AWS OIDC e crea un ruolo IAM per Bedrock
   • Google Vertex AI: Configura Workload Identity Federation per GitLab → GCP
2. Aggiungi credenziali di progetto per le operazioni dell’API GitLab:
   • Utilizza CI_JOB_TOKEN per impostazione predefinita, o crea un Project Access Token con ambito api
   • Archivia come GITLAB_ACCESS_TOKEN (mascherato) se utilizzi un PAT
3. Aggiungi il lavoro Claude a .gitlab-ci.yml (vedi esempi di seguito)
4. (Facoltativo) Abilita trigger basati su menzioni:
   • Aggiungi un webhook di progetto per “Commenti (note)” al tuo listener di eventi (se ne utilizzi uno)
   • Fai in modo che il listener chiami l’API di attivazione della pipeline con variabili come AI_FLOW_INPUT e AI_FLOW_CONTEXT quando un commento contiene @claude

​

Esempi di casi d’uso

​

Trasforma i problemi in MR

@claude implement this feature based on the issue description

​

Ottieni aiuto nell’implementazione

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

​

Correggi i bug rapidamente

@claude fix the TypeError in the user dashboard component

​

Utilizzo con AWS Bedrock e Google Vertex AI

# Per AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

​

Esempi di configurazione

​

.gitlab-ci.yml di base (Claude API)

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  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
    - npm install -g @anthropic-ai/claude-code
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "${AI_FLOW_INPUT:-'Summarize recent changes and suggest improvements'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  # Claude Code utilizzerà ANTHROPIC_API_KEY dalle variabili CI/CD

​

Esempio di lavoro AWS Bedrock (OIDC)

• Amazon Bedrock abilitato con accesso ai tuoi modelli Claude scelti
• GitLab OIDC configurato in AWS con un ruolo che si fida del tuo progetto e dei rami GitLab
• Ruolo IAM con autorizzazioni Bedrock (privilegi minimi consigliati)

• AWS_ROLE_TO_ASSUME: ARN del ruolo IAM per l’accesso a Bedrock
• AWS_REGION: Regione Bedrock (ad esempio, us-west-2)

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apk add --no-cache bash curl jq git python3 py3-pip
    - pip install --no-cache-dir awscli
    - npm install -g @anthropic-ai/claude-code
    # Scambia il token OIDC di GitLab con le credenziali AWS
    - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"
    - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi
    - >
      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"

​

Esempio di lavoro Google Vertex AI (Workload Identity Federation)

• API Vertex AI abilitata nel tuo progetto GCP
• Workload Identity Federation configurata per fidarsi di GitLab OIDC
• Un account di servizio con autorizzazioni Vertex AI

• GCP_WORKLOAD_IDENTITY_PROVIDER: Nome della risorsa del provider completo
• GCP_SERVICE_ACCOUNT: Email dell’account di servizio
• CLOUD_ML_REGION: Regione Vertex (ad esempio, us-east5)

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  before_script:
    - apt-get update && apt-get install -y git nodejs npm && apt-get clean
    - npm install -g @anthropic-ai/claude-code
    # Autentica a Google Cloud tramite WIF (nessuna chiave scaricata)
    - >
      gcloud auth login --cred-file=<(cat <<EOF
      {
        "type": "external_account",
        "audience": "${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken",
        "token_url": "https://sts.googleapis.com/v1/token"
      }
      EOF
      )
    - gcloud config set project "$(gcloud projects list --format='value(projectId)' --filter="name:${CI_PROJECT_NAMESPACE}" | head -n1)" || true
  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"

​

Migliori pratiche

​

Configurazione CLAUDE.md

​

Considerazioni sulla sicurezza

• Aggiungi ANTHROPIC_API_KEY come variabile mascherata (e proteggila se necessario)
• Utilizza OIDC specifico del provider dove possibile (nessuna chiave di lunga durata)
• Limita le autorizzazioni del lavoro e l’uscita della rete
• Rivedi i MR di Claude come qualsiasi altro collaboratore

​

Ottimizzazione delle prestazioni

• Mantieni CLAUDE.md focalizzato e conciso
• Fornisci descrizioni chiare di problemi/MR per ridurre le iterazioni
• Configura timeout di lavoro ragionevoli per evitare esecuzioni incontrollate
• Memorizza nella cache npm e installa i pacchetti nei runner dove possibile

​

Costi CI

• Tempo del runner GitLab:
  • Claude viene eseguito sui tuoi runner GitLab e consuma minuti di calcolo
  • Consulta la fatturazione del runner del tuo piano GitLab per i dettagli
• Costi API:
  • Ogni interazione Claude consuma token in base alle dimensioni del prompt e della risposta
  • L’utilizzo dei token varia in base alla complessità dell’attività e alle dimensioni della base di codice
  • Consulta Prezzi Anthropic per i dettagli
• Suggerimenti per l’ottimizzazione dei costi:
  • Utilizza comandi @claude specifici per ridurre i turni non necessari
  • Imposta valori max_turns e timeout di lavoro appropriati
  • Limita la concorrenza per controllare le esecuzioni parallele

​

Sicurezza e governance

• Ogni lavoro viene eseguito in un contenitore isolato con accesso di rete limitato
• Le modifiche di Claude passano attraverso i MR in modo che i revisori vedano ogni diff
• Le regole di protezione dei rami e approvazione si applicano al codice generato da IA
• Claude Code utilizza autorizzazioni con ambito workspace per limitare le scritture
• I costi rimangono sotto il tuo controllo perché porti le tue credenziali del provider

​

Risoluzione dei problemi

​

Claude non risponde ai comandi @claude

• Verifica che la tua pipeline sia attivata (manualmente, evento MR o tramite listener di note/webhook)
• Assicurati che le variabili CI/CD (ANTHROPIC_API_KEY o impostazioni del provider cloud) siano presenti e non mascherate
• Controlla che il commento contenga @claude (non /claude) e che il tuo trigger di menzione sia configurato

​

Il lavoro non può scrivere commenti o aprire MR

• Assicurati che CI_JOB_TOKEN abbia autorizzazioni sufficienti per il progetto, o utilizza un Project Access Token con ambito api
• Controlla che lo strumento mcp__gitlab sia abilitato in --allowedTools
• Conferma che il lavoro viene eseguito nel contesto del MR o ha contesto sufficiente tramite variabili AI_FLOW_*

​

Errori di autenticazione

• Per Claude API: Conferma che ANTHROPIC_API_KEY sia valida e non scaduta
• Per Bedrock/Vertex: Verifica la configurazione OIDC/WIF, l’impersonificazione del ruolo e i nomi segreti; conferma la disponibilità della regione e del modello

​

Configurazione avanzata

​

Parametri e variabili comuni

• prompt / prompt_file: Fornisci istruzioni inline (-p) o tramite un file
• max_turns: Limita il numero di iterazioni avanti e indietro
• timeout_minutes: Limita il tempo di esecuzione totale
• ANTHROPIC_API_KEY: Richiesto per l’API Claude (non utilizzato per Bedrock/Vertex)
• Ambiente specifico del provider: AWS_REGION, variabili di progetto/regione per Vertex

​

Personalizzazione del comportamento di Claude

1. CLAUDE.md: Definisci standard di codifica, requisiti di sicurezza e convenzioni di progetto. Claude legge questo durante le esecuzioni e segue le tue regole.
2. Prompt personalizzati: Passa istruzioni specifiche dell’attività tramite prompt/prompt_file nel lavoro. Utilizza prompt diversi per lavori diversi (ad esempio, revisione, implementazione, refactoring).