Claude Code GitLab CI/CD

Scopri come integrare Claude Code nel tuo flusso di lavoro di sviluppo con 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 spiegazione
Implementazione automatizzata: Trasformate i problemi in codice funzionante con un singolo comando o menzione
Consapevole 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, Amazon Bedrock o Google Vertex AI per soddisfare le esigenze di residenza dei dati e approvvigionamento
Sicuro per impostazione predefinita: Viene eseguito nei vostri runner GitLab con la vostra protezione dei rami e approvazioni

Come funziona

Claude Code utilizza GitLab CI/CD per eseguire attività di intelligenza artificiale in lavori isolati e eseguire il commit dei risultati tramite MR:

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.
Astrazione del provider: Utilizzate il provider che si adatta al vostro ambiente:
- Claude API (SaaS)
- Amazon Bedrock (accesso basato su IAM, opzioni multi-regione)
- Google Vertex AI (nativo GCP, Workload Identity Federation)
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.

Scegliete endpoint regionali per ridurre la latenza e soddisfare i requisiti di sovranità dei dati mentre utilizzate gli accordi cloud esistenti.

Cosa può fare Claude?

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

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

Il modo più veloce per iniziare è aggiungere un lavoro minimo al vostro .gitlab-ci.yml e impostare la vostra chiave API come variabile mascherata.

Aggiungere una variabile CI/CD mascherata
- Andate a Impostazioni → CI/CD → Variabili
- Aggiungete ANTHROPIC_API_KEY (mascherata, protetta secondo necessità)
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

Dopo aver aggiunto il lavoro e la vostra variabile ANTHROPIC_API_KEY, testate eseguendo il lavoro manualmente da CI/CD → Pipeline, oppure attivate da un MR per consentire a Claude di proporre aggiornamenti in un ramo e aprire un MR se necessario.

Configurazione manuale (consigliata per la produzione)

Se preferite una configurazione più controllata o avete bisogno di provider aziendali:

Configurare l'accesso al provider:
- Claude API: Creare e archiviare ANTHROPIC_API_KEY come variabile CI/CD mascherata
- Amazon Bedrock: Configurare GitLab → AWS OIDC e creare un ruolo IAM per Bedrock
- Google Vertex AI: Configurare Workload Identity Federation per GitLab → GCP
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
Aggiungere il lavoro Claude a .gitlab-ci.yml (vedere gli esempi di seguito)
(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

Esempi di casi d'uso

Trasformare i problemi in MR

In un commento di problema:

@claude implement this feature based on the issue description

Claude analizza il problema e la base di codice, scrive le modifiche in un ramo e apre un MR per la revisione.

Ottenere aiuto nell'implementazione

In una discussione MR:

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

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

Correggere i bug rapidamente

In un commento di problema o MR:

@claude fix the TypeError in the user dashboard component

Claude individua il bug, implementa una correzione e aggiorna il ramo o apre un nuovo MR.

Utilizzo con Amazon Bedrock e Google Vertex AI

Per ambienti aziendali, potete eseguire Claude Code interamente sulla vostra infrastruttura cloud con la stessa esperienza per gli sviluppatori.

Prerequisiti

Prima di configurare Claude Code con Amazon Bedrock, avete bisogno di:

Un account AWS con accesso ad Amazon Bedrock ai modelli Claude desiderati
GitLab configurato come provider di identità OIDC in AWS IAM
Un ruolo IAM con autorizzazioni Bedrock e una politica di trust limitata al vostro progetto/rami GitLab
Variabili CI/CD GitLab per l'assunzione del ruolo:

AWS_ROLE_TO_ASSUME (ARN del ruolo)
AWS_REGION (regione Bedrock)

Istruzioni di configurazione

Configurate AWS per consentire ai lavori CI di GitLab di assumere un ruolo IAM tramite OIDC (nessuna chiave statica).

Configurazione richiesta:

Abilitare Amazon Bedrock e richiedere l'accesso ai vostri modelli Claude target
Creare un provider OIDC IAM per GitLab se non già presente
Creare un ruolo IAM attendibile dal provider OIDC di GitLab, limitato al vostro progetto e rami protetti
Allegare autorizzazioni con privilegi minimi per le API di invocazione Bedrock

Valori richiesti da archiviare nelle variabili CI/CD:

AWS_ROLE_TO_ASSUME
AWS_REGION

Aggiungete le variabili in Impostazioni → CI/CD → Variabili:

# Per Amazon Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

Utilizzate l'esempio di lavoro Amazon Bedrock sopra per scambiare il token di lavoro GitLab con credenziali AWS temporanee in fase di esecuzione.

Prerequisiti

Prima di configurare Claude Code con Google Vertex AI, avete bisogno di:

Un progetto Google Cloud con:

API Vertex AI abilitata
Workload Identity Federation configurata per attendere OIDC di GitLab

Un account di servizio dedicato con solo i ruoli Vertex AI richiesti
Variabili CI/CD GitLab per WIF:

GCP_WORKLOAD_IDENTITY_PROVIDER (nome completo della risorsa)
GCP_SERVICE_ACCOUNT (email dell'account di servizio)

Istruzioni di configurazione

Configurate Google Cloud per consentire ai lavori CI di GitLab di rappresentare un account di servizio tramite Workload Identity Federation.

Configurazione richiesta:

Abilitare API IAM Credentials, STS API e Vertex AI API
Creare un Workload Identity Pool e un provider per OIDC di GitLab
Creare un account di servizio dedicato con ruoli Vertex AI
Concedere al principale WIF l'autorizzazione per rappresentare l'account di servizio

Valori richiesti da archiviare nelle variabili CI/CD:

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT

Aggiungete le variabili in Impostazioni → CI/CD → Variabili:

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

Utilizzate l'esempio di lavoro Google Vertex AI sopra per autenticarvi senza archiviare le chiavi.

Esempi di configurazione

Di seguito sono riportati frammenti pronti all'uso che potete adattare alla vostra pipeline.

.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 Amazon Bedrock (OIDC)

Prerequisiti:

Amazon Bedrock abilitato con accesso ai vostri modelli Claude scelti
OIDC di GitLab configurato in AWS con un ruolo che attendibile al vostro progetto e rami GitLab
Ruolo IAM con autorizzazioni Bedrock (privilegi minimi consigliati)

Variabili CI/CD richieste:

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 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)

Prerequisiti:

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

Variabili CI/CD richieste:

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

Create un file CLAUDE.md nella 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 vostre convenzioni quando propone modifiche.

Considerazioni sulla sicurezza

Non eseguite mai il commit di chiavi API o credenziali cloud nel vostro repository. Utilizzate sempre le variabili CI/CD di GitLab:

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 dei lavori 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 installazioni di pacchetti nei runner dove possibile

Costi CI

Quando utilizzate Claude Code con GitLab CI/CD, siate consapevoli dei costi associati:

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 max_turns e timeout di lavoro appropriati
- 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 abbia 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

Claude Code supporta questi input comunemente utilizzati:

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

Potete guidare Claude in due modi principali:

CLAUDE.md: Definite standard di codifica, requisiti di sicurezza e convenzioni di progetto. Claude legge questo durante le esecuzioni e segue le vostre regole.
Prompt personalizzati: Passate istruzioni specifiche dell'attività tramite prompt/prompt_file nel lavoro. Utilizzate prompt diversi per lavori diversi (ad esempio, revisione, implementazione, refactoring).

gitlab-ci-cd.md +85 −29

16 Questa integrazione è costruita sulla base di [Claude Code CLI e Agent SDK](/it/agent-sdk/overview), consentendo l'uso programmatico di Claude nei vostri lavori CI/CD e flussi di lavoro di automazione personalizzati.16 Questa integrazione è costruita sulla base di [Claude Code CLI e Agent SDK](/it/agent-sdk/overview), consentendo l'uso programmatico di Claude nei vostri lavori CI/CD e flussi di lavoro di automazione personalizzati.

17</Note>17</Note>

18 18

~~19## Perché utilizzare Claude Code con GitLab?~~19<h2 id="why-use-claude-code-with-gitlab">

20 Perché utilizzare Claude Code con GitLab?

21</h2>

20 22

21* **Creazione istantanea di MR**: Descrivete ciò di cui avete bisogno e Claude propone un MR completo con modifiche e spiegazione23* **Creazione istantanea di MR**: Descrivete ciò di cui avete bisogno e Claude propone un MR completo con modifiche e spiegazione

22* **Implementazione automatizzata**: Trasformate i problemi in codice funzionante con un singolo comando o menzione24* **Implementazione automatizzata**: Trasformate i problemi in codice funzionante con un singolo comando o menzione

25* **Pronto per l'azienda**: Scegliete Claude API, Amazon Bedrock o Google Vertex AI per soddisfare le esigenze di residenza dei dati e approvvigionamento27* **Pronto per l'azienda**: Scegliete Claude API, Amazon Bedrock o Google Vertex AI per soddisfare le esigenze di residenza dei dati e approvvigionamento

26* **Sicuro per impostazione predefinita**: Viene eseguito nei vostri runner GitLab con la vostra protezione dei rami e approvazioni28* **Sicuro per impostazione predefinita**: Viene eseguito nei vostri runner GitLab con la vostra protezione dei rami e approvazioni

27 29

~~28## Come funziona~~30<h2 id="how-it-works">

31 Come funziona

32</h2>

29 33

30Claude Code utilizza GitLab CI/CD per eseguire attività di intelligenza artificiale in lavori isolati e eseguire il commit dei risultati tramite MR:34Claude Code utilizza GitLab CI/CD per eseguire attività di intelligenza artificiale in lavori isolati e eseguire il commit dei risultati tramite MR:

31 35

40 44

41Scegliete endpoint regionali per ridurre la latenza e soddisfare i requisiti di sovranità dei dati mentre utilizzate gli accordi cloud esistenti.45Scegliete endpoint regionali per ridurre la latenza e soddisfare i requisiti di sovranità dei dati mentre utilizzate gli accordi cloud esistenti.

42 46

~~43## Cosa può fare Claude?~~47<h2 id="what-can-claude-do">

48 Cosa può fare Claude?

49</h2>

44 50

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

46 52

50* Correggere bug e regressioni identificati da test o commenti56* Correggere bug e regressioni identificati da test o commenti

51* Rispondere ai commenti di follow-up per iterare sulle modifiche richieste57* Rispondere ai commenti di follow-up per iterare sulle modifiche richieste

52 58

~~53## Configurazione~~59<h2 id="setup">

60 Configurazione

61</h2>

54 62

~~55### Configurazione rapida~~63<h3 id="quick-setup">

64 Configurazione rapida

65</h3>

56 66

57Il modo più veloce per iniziare è aggiungere un lavoro minimo al vostro `.gitlab-ci.yml` e impostare la vostra chiave API come variabile mascherata.67Il modo più veloce per iniziare è aggiungere un lavoro minimo al vostro `.gitlab-ci.yml` e impostare la vostra chiave API come variabile mascherata.

58 68

98Dopo aver aggiunto il lavoro e la vostra variabile `ANTHROPIC_API_KEY`, testate eseguendo il lavoro manualmente da **CI/CD** → **Pipeline**, oppure attivate da un MR per consentire a Claude di proporre aggiornamenti in un ramo e aprire un MR se necessario.108Dopo aver aggiunto il lavoro e la vostra variabile `ANTHROPIC_API_KEY`, testate eseguendo il lavoro manualmente da **CI/CD** → **Pipeline**, oppure attivate da un MR per consentire a Claude di proporre aggiornamenti in un ramo e aprire un MR se necessario.

99 109

100<Note>110<Note>

101 Per eseguire su Amazon Bedrock o Google Vertex AI invece dell'API Claude, consultate la sezione [Utilizzo con Amazon Bedrock e Google Vertex AI](#utilizzo-con-amazon-bedrock--google-vertex-ai) di seguito per la configurazione dell'autenticazione e dell'ambiente.111 Per eseguire su Amazon Bedrock o Google Vertex AI invece dell'API Claude, consultate la sezione [Utilizzo con Amazon Bedrock e Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) di seguito per la configurazione dell'autenticazione e dell'ambiente.

102</Note>112</Note>

103 113

104### Configurazione manuale (consigliata per la produzione)114<h3 id="manual-setup-recommended-for-production">

115 Configurazione manuale (consigliata per la produzione)

116</h3>

105 117

106Se preferite una configurazione più controllata o avete bisogno di provider aziendali:118Se preferite una configurazione più controllata o avete bisogno di provider aziendali:

107 119

120 * Aggiungere un webhook di progetto per "Commenti (note)" al vostro listener di eventi (se ne utilizzate uno)132 * Aggiungere un webhook di progetto per "Commenti (note)" al vostro listener di eventi (se ne utilizzate uno)

121 * 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`133 * 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`

122 134

123## Esempi di casi d'uso135<h2 id="example-use-cases">

136 Esempi di casi d'uso

137</h2>

124 138

125### Trasformare i problemi in MR139<h3 id="turn-issues-into-mrs">

140 Trasformare i problemi in MR

141</h3>

126 142

127In un commento di problema:143In un commento di problema:

128 144

132 148

133Claude analizza il problema e la base di codice, scrive le modifiche in un ramo e apre un MR per la revisione.149Claude analizza il problema e la base di codice, scrive le modifiche in un ramo e apre un MR per la revisione.

134 150

135### Ottenere aiuto nell'implementazione151<h3 id="get-implementation-help">

152 Ottenere aiuto nell'implementazione

153</h3>

136 154

137In una discussione MR:155In una discussione MR:

138 156

142 160

143Claude propone modifiche, aggiunge codice con caching appropriato e aggiorna il MR.161Claude propone modifiche, aggiunge codice con caching appropriato e aggiorna il MR.

144 162

145### Correggere i bug rapidamente163<h3 id="fix-bugs-quickly">

164 Correggere i bug rapidamente

165</h3>

146 166

147In un commento di problema o MR:167In un commento di problema o MR:

148 168

152 172

153Claude individua il bug, implementa una correzione e aggiorna il ramo o apre un nuovo MR.173Claude individua il bug, implementa una correzione e aggiorna il ramo o apre un nuovo MR.

154 174

155## Utilizzo con Amazon Bedrock e Google Vertex AI175<h2 id="using-with-amazon-bedrock--google-vertex-ai">

176 Utilizzo con Amazon Bedrock e Google Vertex AI

177</h2>

156 178

157Per ambienti aziendali, potete eseguire Claude Code interamente sulla vostra infrastruttura cloud con la stessa esperienza per gli sviluppatori.179Per ambienti aziendali, potete eseguire Claude Code interamente sulla vostra infrastruttura cloud con la stessa esperienza per gli sviluppatori.

158 180

238 </Tab>260 </Tab>

239</Tabs>261</Tabs>

240 262

241## Esempi di configurazione263<h2 id="configuration-examples">

264 Esempi di configurazione

265</h2>

242 266

243Di seguito sono riportati frammenti pronti all'uso che potete adattare alla vostra pipeline.267Di seguito sono riportati frammenti pronti all'uso che potete adattare alla vostra pipeline.

244 268

245### .gitlab-ci.yml di base (Claude API)269<h3 id="basic-gitlab-ci-yml-claude-api">

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

271</h3>

246 272

247```yaml theme={null}273```yaml theme={null}

248stages:274stages:

271 # Claude Code utilizzerà ANTHROPIC_API_KEY dalle variabili CI/CD297 # Claude Code utilizzerà ANTHROPIC_API_KEY dalle variabili CI/CD

272```298```

273 299

274### Esempio di lavoro Amazon Bedrock (OIDC)300<h3 id="amazon-bedrock-job-example-oidc">

301 Esempio di lavoro Amazon Bedrock (OIDC)

302</h3>

275 303

276**Prerequisiti:**304**Prerequisiti:**

277 305

322 Gli ID modello per Bedrock includono prefissi specifici della regione (ad esempio, `us.anthropic.claude-sonnet-4-6`). Passate il modello desiderato tramite la configurazione del lavoro o il prompt se il vostro flusso di lavoro lo supporta.350 Gli ID modello per Bedrock includono prefissi specifici della regione (ad esempio, `us.anthropic.claude-sonnet-4-6`). Passate il modello desiderato tramite la configurazione del lavoro o il prompt se il vostro flusso di lavoro lo supporta.

323</Note>351</Note>

324 352

325### Esempio di lavoro Google Vertex AI (Workload Identity Federation)353<h3 id="google-vertex-ai-job-example-workload-identity-federation">

354 Esempio di lavoro Google Vertex AI (Workload Identity Federation)

355</h3>

326 356

327**Prerequisiti:**357**Prerequisiti:**

328 358

375 Con Workload Identity Federation, non è necessario archiviare le chiavi dell'account di servizio. Utilizzate condizioni di trust specifiche del repository e account di servizio con privilegi minimi.405 Con Workload Identity Federation, non è necessario archiviare le chiavi dell'account di servizio. Utilizzate condizioni di trust specifiche del repository e account di servizio con privilegi minimi.

376</Note>406</Note>

377 407

378## Best practice408<h2 id="best-practices">

409 Best practice

410</h2>

379 411

380### Configurazione CLAUDE.md412<h3 id="claude-md-configuration">

413 Configurazione CLAUDE.md

414</h3>

381 415

382Create un file `CLAUDE.md` nella 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 vostre convenzioni quando propone modifiche.416Create un file `CLAUDE.md` nella 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 vostre convenzioni quando propone modifiche.

383 417

384### Considerazioni sulla sicurezza418<h3 id="security-considerations">

419 Considerazioni sulla sicurezza

420</h3>

385 421

386**Non eseguite mai il commit di chiavi API o credenziali cloud nel vostro repository**. Utilizzate sempre le variabili CI/CD di GitLab:422**Non eseguite mai il commit di chiavi API o credenziali cloud nel vostro repository**. Utilizzate sempre le variabili CI/CD di GitLab:

387 423

390* Limitate le autorizzazioni dei lavori e l'uscita di rete426* Limitate le autorizzazioni dei lavori e l'uscita di rete

391* Revisionate i MR di Claude come qualsiasi altro contributore427* Revisionate i MR di Claude come qualsiasi altro contributore

392 428

393### Ottimizzazione delle prestazioni429<h3 id="optimizing-performance">

430 Ottimizzazione delle prestazioni

431</h3>

394 432

395* Mantenete `CLAUDE.md` focalizzato e conciso433* Mantenete `CLAUDE.md` focalizzato e conciso

396* Fornite descrizioni chiare di problemi/MR per ridurre le iterazioni434* Fornite descrizioni chiare di problemi/MR per ridurre le iterazioni

397* Configurate timeout di lavoro ragionevoli per evitare esecuzioni incontrollate435* Configurate timeout di lavoro ragionevoli per evitare esecuzioni incontrollate

398* Memorizzate nella cache npm e installazioni di pacchetti nei runner dove possibile436* Memorizzate nella cache npm e installazioni di pacchetti nei runner dove possibile

399 437

400### Costi CI438<h3 id="ci-costs">

439 Costi CI

440</h3>

401 441

402Quando utilizzate Claude Code con GitLab CI/CD, siate consapevoli dei costi associati:442Quando utilizzate Claude Code con GitLab CI/CD, siate consapevoli dei costi associati:

403 443

415 * Impostate valori `max_turns` e timeout di lavoro appropriati455 * Impostate valori `max_turns` e timeout di lavoro appropriati

416 * Limitate la concorrenza per controllare le esecuzioni parallele456 * Limitate la concorrenza per controllare le esecuzioni parallele

417 457

418## Sicurezza e governance458<h2 id="security-and-governance">

459 Sicurezza e governance

460</h2>

419 461

420* Ogni lavoro viene eseguito in un contenitore isolato con accesso di rete limitato462* Ogni lavoro viene eseguito in un contenitore isolato con accesso di rete limitato

421* Le modifiche di Claude passano attraverso MR in modo che i revisori vedano ogni diff463* Le modifiche di Claude passano attraverso MR in modo che i revisori vedano ogni diff

423* Claude Code utilizza autorizzazioni con ambito workspace per limitare le scritture465* Claude Code utilizza autorizzazioni con ambito workspace per limitare le scritture

424* I costi rimangono sotto il vostro controllo perché portate le vostre credenziali del provider466* I costi rimangono sotto il vostro controllo perché portate le vostre credenziali del provider

425 467

426## Risoluzione dei problemi468<h2 id="troubleshooting">

469 Risoluzione dei problemi

470</h2>

427 471

428### Claude non risponde ai comandi @claude472<h3 id="claude-not-responding-to-claude-commands">

473 Claude non risponde ai comandi @claude

474</h3>

429 475

430* Verificate che la vostra pipeline sia attivata (manualmente, evento MR o tramite listener di note/webhook)476* Verificate che la vostra pipeline sia attivata (manualmente, evento MR o tramite listener di note/webhook)

431* Assicuratevi che le variabili CI/CD (`ANTHROPIC_API_KEY` o impostazioni del provider cloud) siano presenti e non mascherate477* Assicuratevi che le variabili CI/CD (`ANTHROPIC_API_KEY` o impostazioni del provider cloud) siano presenti e non mascherate

432* Controllate che il commento contenga `@claude` (non `/claude`) e che il vostro trigger di menzione sia configurato478* Controllate che il commento contenga `@claude` (non `/claude`) e che il vostro trigger di menzione sia configurato

433 479

434### Il lavoro non può scrivere commenti o aprire MR480<h3 id="job-can’t-write-comments-or-open-mrs">

481 Il lavoro non può scrivere commenti o aprire MR

482</h3>

435 483

436* Assicuratevi che `CI_JOB_TOKEN` abbia autorizzazioni sufficienti per il progetto, oppure utilizzate un Project Access Token con ambito `api`484* Assicuratevi che `CI_JOB_TOKEN` abbia autorizzazioni sufficienti per il progetto, oppure utilizzate un Project Access Token con ambito `api`

437* Controllate che lo strumento `mcp__gitlab` sia abilitato in `--allowedTools`485* Controllate che lo strumento `mcp__gitlab` sia abilitato in `--allowedTools`

438* Confermate che il lavoro viene eseguito nel contesto del MR o abbia contesto sufficiente tramite variabili `AI_FLOW_*`486* Confermate che il lavoro viene eseguito nel contesto del MR o abbia contesto sufficiente tramite variabili `AI_FLOW_*`

439 487

440### Errori di autenticazione488<h3 id="authentication-errors">

489 Errori di autenticazione

490</h3>

441 491

442* **Per Claude API**: Confermate che `ANTHROPIC_API_KEY` sia valida e non scaduta492* **Per Claude API**: Confermate che `ANTHROPIC_API_KEY` sia valida e non scaduta

443* **Per Bedrock/Vertex**: Verificate la configurazione OIDC/WIF, l'impersonificazione del ruolo e i nomi segreti; confermate la disponibilità della regione e del modello493* **Per Bedrock/Vertex**: Verificate la configurazione OIDC/WIF, l'impersonificazione del ruolo e i nomi segreti; confermate la disponibilità della regione e del modello

444 494

445## Configurazione avanzata495<h2 id="advanced-configuration">

496 Configurazione avanzata

497</h2>

446 498

447### Parametri e variabili comuni499<h3 id="common-parameters-and-variables">

500 Parametri e variabili comuni

501</h3>

448 502

449Claude Code supporta questi input comunemente utilizzati:503Claude Code supporta questi input comunemente utilizzati:

450 504

458 I flag e i parametri esatti possono variare in base alla versione di `@anthropic-ai/claude-code`. Eseguite `claude --help` nel vostro lavoro per vedere le opzioni supportate.512 I flag e i parametri esatti possono variare in base alla versione di `@anthropic-ai/claude-code`. Eseguite `claude --help` nel vostro lavoro per vedere le opzioni supportate.

459</Note>513</Note>

460 514

461### Personalizzazione del comportamento di Claude515<h3 id="customizing-claude’s-behavior">

516 Personalizzazione del comportamento di Claude

517</h3>

462 518

463Potete guidare Claude in due modi principali:519Potete guidare Claude in due modi principali:

464 520

gitlab-ci-cd.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

Claude Code GitLab CI/CD

Perché utilizzare Claude Code con GitLab?

Come funziona

Cosa può fare Claude?

Configurazione

Configurazione rapida

Configurazione manuale (consigliata per la produzione)

Esempi di casi d'uso

Trasformare i problemi in MR

Ottenere aiuto nell'implementazione

Correggere i bug rapidamente

Utilizzo con Amazon Bedrock e Google Vertex AI

Prerequisiti

Istruzioni di configurazione

Prerequisiti

Istruzioni di configurazione

Esempi di configurazione

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

Esempio di lavoro Amazon Bedrock (OIDC)

Esempio di lavoro Google Vertex AI (Workload Identity Federation)

Best practice

Configurazione CLAUDE.md

Considerazioni sulla sicurezza

Ottimizzazione delle prestazioni

Costi CI

Sicurezza e governance

Risoluzione dei problemi

Claude non risponde ai comandi @claude

Il lavoro non può scrivere commenti o aprire MR

Errori di autenticazione

Configurazione avanzata

Parametri e variabili comuni

Personalizzazione del comportamento di Claude