Claude Code GitLab CI/CD

​

Perché usare Claude Code con GitLab?

• Creazione istantanea di MR: Descrivi quello che ti serve, e Claude propone una MR completa con modifiche e spiegazione
• Implementazione automatizzata: Trasforma le issue in codice funzionante con un singolo comando o menzione
• Consapevole del progetto: Claude segue le tue linee guida CLAUDE.md e i pattern di codice esistenti
• Configurazione semplice: Aggiungi un job a .gitlab-ci.yml e una variabile CI/CD mascherata
• Pronto per l’enterprise: Scegli Anthropic API, AWS Bedrock, o Google Vertex AI per soddisfare le esigenze di residenza dei dati e approvvigionamento
• Sicuro per impostazione predefinita: Funziona nei tuoi runner GitLab con la tua protezione dei branch e approvazioni

​

Come funziona

Claude Code usa GitLab CI/CD per eseguire attività AI in job isolati e committare i risultati tramite MR:

1. Orchestrazione guidata da eventi: GitLab ascolta i trigger che scegli (ad esempio, un commento che menziona @claude in una issue, MR, o thread di revisione). Il job raccoglie il contesto dal thread e repository, costruisce prompt da quell’input, ed esegue Claude Code.

2. Astrazione del provider: Usa il provider che si adatta al tuo ambiente:

   • Anthropic API (SaaS)
   • AWS Bedrock (accesso basato su IAM, opzioni cross-region)
   • Google Vertex AI (nativo GCP, Workload Identity Federation)

3. Esecuzione sandboxed: Ogni interazione viene eseguita in un container con regole di rete e filesystem rigorose. Claude Code applica permessi con scope del workspace per limitare le scritture. Ogni modifica fluisce attraverso una MR così i revisori vedono il diff e le approvazioni si applicano ancora.

Scegli endpoint regionali per ridurre la latenza e soddisfare i requisiti di sovranità dei dati utilizzando accordi cloud esistenti.

​

Cosa può fare Claude?

Claude Code abilita potenti flussi di lavoro CI/CD che trasformano il modo in cui lavori con il codice:

• Creare e aggiornare MR da descrizioni di issue o commenti
• Analizzare regressioni delle prestazioni e proporre ottimizzazioni
• Implementare funzionalità direttamente in un branch, poi aprire una MR
• Correggere bug e regressioni identificati da test o commenti
• Rispondere a commenti di follow-up per iterare sui cambiamenti richiesti

​

Configurazione

​

Configurazione rapida

Il modo più veloce per iniziare è aggiungere un job minimale al tuo .gitlab-ci.yml e impostare la tua chiave API come variabile mascherata.

1. Aggiungi una variabile CI/CD mascherata

   • Vai a Settings → CI/CD → Variables
   • Aggiungi ANTHROPIC_API_KEY (mascherata, protetta se necessario)

2. Aggiungi un job Claude a .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Regola le rules per adattarle a come vuoi triggerare il job:
  # - 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:
    # Opzionale: avvia un server GitLab MCP se la tua configurazione ne fornisce uno
    - /bin/gitlab-mcp-server || true
    # Usa variabili AI_FLOW_* quando invochi 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:-'Rivedi questa MR e implementa i cambiamenti richiesti'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug

Dopo aver aggiunto il job e la tua variabile ANTHROPIC_API_KEY, testa eseguendo il job manualmente da CI/CD → Pipelines, o triggeralo da una MR per far proporre a Claude aggiornamenti in un branch e aprire una MR se necessario.

​

Configurazione manuale (raccomandata per produzione)

Se preferisci una configurazione più controllata o hai bisogno di provider enterprise:

1. Configura l’accesso al provider:

   • Anthropic API: Crea e memorizza 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 del progetto per operazioni API GitLab:

   • Usa CI_JOB_TOKEN per impostazione predefinita, o crea un Project Access Token con scope api
   • Memorizza come GITLAB_ACCESS_TOKEN (mascherato) se usi un PAT

3. Aggiungi il job Claude a .gitlab-ci.yml (vedi esempi sotto)

4. (Opzionale) Abilita trigger guidati da menzioni:

   • Aggiungi un webhook del progetto per “Comments (notes)” al tuo event listener (se ne usi uno)
   • Fai chiamare al listener l’API trigger della pipeline con variabili come AI_FLOW_INPUT e AI_FLOW_CONTEXT quando un commento contiene @claude

​

Esempi di casi d’uso

​

Trasforma issue in MR

In un commento di issue:

@claude implementa questa funzionalità basata sulla descrizione dell'issue

Claude analizza l’issue e la codebase, scrive modifiche in un branch, e apre una MR per la revisione.

​

Ottieni aiuto per l’implementazione

In una discussione MR:

@claude suggerisci un approccio concreto per cachare i risultati di questa chiamata API

Claude propone modifiche, aggiunge codice con caching appropriato, e aggiorna la MR.

​

Correggi bug rapidamente

In un commento di issue o MR:

@claude correggi il TypeError nel componente dashboard utente

Claude localizza il bug, implementa una correzione, e aggiorna il branch o apre una nuova MR.

​

Uso con AWS Bedrock & Google Vertex AI

Per ambienti enterprise, puoi eseguire Claude Code interamente sulla tua infrastruttura cloud con la stessa esperienza sviluppatore.

# Per AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# Per AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# Per Google Vertex AI:
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION (ad esempio, us-east5)

​

Esempi di configurazione

Sotto ci sono snippet pronti all’uso che puoi adattare alla tua pipeline.

​

.gitlab-ci.yml base (Anthropic 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:-'Riassumi i cambiamenti recenti e suggerisci miglioramenti'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  # Claude Code userà ANTHROPIC_API_KEY dalle variabili CI/CD

​

Esempio job AWS Bedrock (OIDC)

Prerequisiti:

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

Variabili CI/CD richieste:

• AWS_ROLE_TO_ASSUME: ARN del ruolo IAM per l’accesso 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 token OIDC GitLab per 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:-'Implementa i cambiamenti richiesti e apri una MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"

​

Esempio job Google Vertex AI (Workload Identity Federation)

Prerequisiti:

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

Variabili CI/CD richieste:

• GCP_WORKLOAD_IDENTITY_PROVIDER: Nome risorsa provider completo
• GCP_SERVICE_ACCOUNT: Email 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:-'Rivedi e aggiorna il codice come richiesto'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"

​

Migliori pratiche

​

Configurazione CLAUDE.md

Crea un file CLAUDE.md alla radice del repository per definire standard di codifica, criteri di revisione, e regole specifiche del progetto. Claude legge questo file durante le esecuzioni e segue le tue convenzioni quando propone modifiche.

​

Considerazioni di sicurezza

Non committare mai chiavi API o credenziali cloud nel tuo repository! Usa sempre le variabili CI/CD GitLab:

• Aggiungi ANTHROPIC_API_KEY come variabile mascherata (e proteggila se necessario)
• Usa OIDC specifico del provider dove possibile (nessuna chiave a lunga durata)
• Limita i permessi del job e l’egress di rete
• Rivedi le MR di Claude come qualsiasi altro contributore

​

Ottimizzazione delle prestazioni

• Mantieni CLAUDE.md focalizzato e conciso
• Fornisci descrizioni chiare di issue/MR per ridurre le iterazioni
• Configura timeout del job sensati per evitare esecuzioni fuori controllo
• Cacheizza npm e installazioni di pacchetti nei runner dove possibile

​

Costi CI

Quando usi Claude Code con GitLab CI/CD, sii consapevole dei costi associati:

• Tempo runner GitLab:

  • Claude viene eseguito sui tuoi runner GitLab e consume minuti di compute
  • Vedi la fatturazione runner del tuo piano GitLab per dettagli

• Costi API:

  • Ogni interazione Claude consume token basati sulla dimensione del prompt e risposta
  • L’uso dei token varia per complessità del task e dimensione della codebase
  • Vedi prezzi Anthropic per dettagli

• Suggerimenti per l’ottimizzazione dei costi:

  • Usa comandi @claude specifici per ridurre turni non necessari
  • Imposta valori appropriati di max_turns e timeout del job
  • Limita la concorrenza per controllare le esecuzioni parallele

​

Sicurezza e governance

• Ogni job viene eseguito in un container isolato con accesso di rete limitato
• Le modifiche di Claude fluiscono attraverso MR così i revisori vedono ogni diff
• La protezione dei branch e le regole di approvazione si applicano al codice generato da AI
• Claude Code usa permessi con scope del 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 triggerata (manualmente, evento MR, o tramite un listener/webhook evento note)
• Assicurati che le variabili CI/CD (ANTHROPIC_API_KEY o impostazioni 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 job non può scrivere commenti o aprire MR

• Assicurati che CI_JOB_TOKEN abbia permessi sufficienti per il progetto, o usa un Project Access Token con scope api
• Controlla che lo strumento mcp__gitlab sia abilitato in --allowedTools
• Conferma che il job viene eseguito nel contesto della MR o abbia abbastanza contesto tramite variabili AI_FLOW_*

​

Errori di autenticazione

• Per Anthropic API: Conferma che ANTHROPIC_API_KEY sia valida e non scaduta
• Per Bedrock/Vertex: Verifica la configurazione OIDC/WIF, impersonazione del ruolo, e nomi dei segreti; conferma disponibilità regione e modello

​

Configurazione avanzata

​

Parametri e variabili comuni

Claude Code supporta questi input comunemente usati:

• 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 totale di esecuzione
• ANTHROPIC_API_KEY: Richiesta per l’API Anthropic (non usata per Bedrock/Vertex)
• Ambiente specifico del provider: AWS_REGION, variabili progetto/regione per Vertex

​

Personalizzazione del comportamento di Claude

Puoi guidare Claude in due modi principali:

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