Claude Code GitLab CI/CD

​

Perché utilizzare Claude Code con GitLab?

• Creazione istantanea di MR: Descrivete ciò di cui avete bisogno e Claude propone un MR completo con modifiche e spiegazioni
• Implementazione automatizzata: Trasformate i problemi in codice funzionante con un singolo comando o menzione
• Consapevolezza del progetto: Claude segue le vostre linee guida CLAUDE.md e i modelli di codice esistenti
• Configurazione semplice: Aggiungete un lavoro a .gitlab-ci.yml e una variabile CI/CD mascherata
• Pronto per l’azienda: Scegliete 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 vostri runner GitLab con la vostra protezione dei rami e 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: Utilizzate il provider che si adatta al vostro 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 filesystem. 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. Aggiungere una variabile CI/CD mascherata
   • Andate a Impostazioni → CI/CD → Variabili
   • Aggiungete ANTHROPIC_API_KEY (mascherata, protetta secondo necessità)
2. Aggiungere un lavoro Claude a .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Regolate le regole per adattarsi a come desiderate 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
    - curl -fsSL https://claude.ai/install.sh | bash
  script:
    # Facoltativo: avviare un server GitLab MCP se la vostra configurazione lo fornisce
    - /bin/gitlab-mcp-server || true
    # Utilizzate le variabili AI_FLOW_* quando richiamate 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. Configurare l’accesso al provider:
   • Claude API: Creare e archiviare ANTHROPIC_API_KEY come variabile CI/CD mascherata
   • AWS Bedrock: Configurare GitLab → AWS OIDC e creare un ruolo IAM per Bedrock
   • Google Vertex AI: Configurare Workload Identity Federation per GitLab → GCP
2. Aggiungere credenziali di progetto per le operazioni dell’API GitLab:
   • Utilizzate CI_JOB_TOKEN per impostazione predefinita, oppure create un Project Access Token con ambito api
   • Archiviate come GITLAB_ACCESS_TOKEN (mascherato) se utilizzate un PAT
3. Aggiungere il lavoro Claude a .gitlab-ci.yml (vedere gli esempi di seguito)
4. (Facoltativo) Abilitare trigger basati su menzioni:
   • Aggiungere un webhook di progetto per “Commenti (note)” al vostro listener di eventi (se ne utilizzate uno)
   • Fare 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

​

Casi d’uso di esempio

​

Trasformare i problemi in MR

@claude implement this feature based on the issue description

​

Ottenere aiuto nell’implementazione

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

​

Correggere 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

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

​

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
    - curl -fsSL https://claude.ai/install.sh | bash
  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 vostri modelli Claude scelti
• GitLab OIDC configurato in AWS con un ruolo che si fida del vostro progetto e 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
    - curl -fsSL https://claude.ai/install.sh | bash
    # Scambiare 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 vostro progetto GCP
• Workload Identity Federation configurata per fidarsi di GitLab OIDC
• Un account di servizio con autorizzazioni Vertex AI

• GCP_WORKLOAD_IDENTITY_PROVIDER: Nome completo della risorsa del provider
• 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 && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # Autenticarsi 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"

​

Best practice

​

Configurazione CLAUDE.md

​

Considerazioni sulla sicurezza

• Aggiungete ANTHROPIC_API_KEY come variabile mascherata (e proteggetela se necessario)
• Utilizzate OIDC specifico del provider dove possibile (nessuna chiave di lunga durata)
• Limitate le autorizzazioni del lavoro e l’uscita di rete
• Revisionate i MR di Claude come qualsiasi altro contributore

​

Ottimizzazione delle prestazioni

• Mantenete CLAUDE.md focalizzato e conciso
• Fornite descrizioni chiare di problemi/MR per ridurre le iterazioni
• Configurate timeout di lavoro ragionevoli per evitare esecuzioni incontrollate
• Memorizzate nella cache npm e gli install di pacchetti nei runner dove possibile

​

Costi CI

• Tempo del runner GitLab:
  • Claude viene eseguito sui vostri runner GitLab e consuma minuti di calcolo
  • Consultate la fatturazione del runner del vostro piano GitLab per i dettagli
• Costi API:
  • Ogni interazione Claude consuma token in base alla dimensione del prompt e della risposta
  • L’utilizzo dei token varia in base alla complessità dell’attività e alla dimensione della base di codice
  • Consultate Prezzi Anthropic per i dettagli
• Suggerimenti per l’ottimizzazione dei costi:
  • Utilizzate comandi @claude specifici per ridurre i turni non necessari
  • Impostate valori appropriati di max_turns e timeout del lavoro
  • Limitate 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 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 vostro controllo perché portate le vostre credenziali del provider

​

Risoluzione dei problemi

​

Claude non risponde ai comandi @claude

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

​

Il lavoro non può scrivere commenti o aprire MR

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

​

Errori di autenticazione

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

​

Configurazione avanzata

​

Parametri e variabili comuni

• prompt / prompt_file: Fornite istruzioni inline (-p) o tramite un file
• max_turns: Limitate il numero di iterazioni avanti e indietro
• timeout_minutes: Limitate 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: Definite gli standard di codifica, i requisiti di sicurezza e le convenzioni del progetto. Claude legge questo durante le esecuzioni e segue le vostre regole.
2. Prompt personalizzati: Passate istruzioni specifiche dell’attività tramite prompt/prompt_file nel lavoro. Utilizzate prompt diversi per lavori diversi (ad esempio, revisione, implementazione, refactoring).