Claude Code GitLab CI/CD

Saiba como integrar Claude Code no seu fluxo de trabalho de desenvolvimento com GitLab CI/CD

Por que usar Claude Code com GitLab?

Criação instantânea de MR: Descreva o que você precisa, e Claude propõe um MR completo com alterações e explicação
Implementação automatizada: Transforme problemas em código funcional com um único comando ou menção
Ciente do projeto: Claude segue suas diretrizes CLAUDE.md e padrões de código existentes
Configuração simples: Adicione um trabalho a .gitlab-ci.yml e uma variável de CI/CD mascarada
Pronto para empresas: Escolha Claude API, Amazon Bedrock ou Google Vertex AI para atender às necessidades de residência de dados e compras
Seguro por padrão: Executa em seus executores GitLab com sua proteção de branch e aprovações

Como funciona

Claude Code usa GitLab CI/CD para executar tarefas de IA em trabalhos isolados e confirmar resultados de volta via MRs:

Orquestração orientada por eventos: GitLab escuta seus gatilhos escolhidos (por exemplo, um comentário que menciona @claude em um problema, MR ou thread de revisão). O trabalho coleta contexto da thread e do repositório, constrói prompts a partir dessa entrada e executa Claude Code.
Abstração de provedor: Use o provedor que se adequa ao seu ambiente:
- Claude API (SaaS)
- Amazon Bedrock (acesso baseado em IAM, opções entre regiões)
- Google Vertex AI (nativo do GCP, Workload Identity Federation)
Execução em sandbox: Cada interação é executada em um contêiner com regras rigorosas de rede e sistema de arquivos. Claude Code impõe permissões com escopo de workspace para restringir gravações. Cada alteração flui através de um MR para que os revisores vejam o diff e as aprovações ainda se apliquem.

Escolha endpoints regionais para reduzir latência e atender aos requisitos de soberania de dados enquanto usa acordos de nuvem existentes.

O que Claude pode fazer?

Claude Code permite fluxos de trabalho poderosos de CI/CD que transformam a forma como você trabalha com código:

Criar e atualizar MRs a partir de descrições ou comentários de problemas
Analisar regressões de desempenho e propor otimizações
Implementar recursos diretamente em um branch, depois abrir um MR
Corrigir bugs e regressões identificados por testes ou comentários
Responder a comentários de acompanhamento para iterar sobre as alterações solicitadas

Configuração

Configuração rápida

A forma mais rápida de começar é adicionar um trabalho mínimo ao seu .gitlab-ci.yml e definir sua chave de API como uma variável mascarada.

Adicione uma variável de CI/CD mascarada
- Vá para Settings → CI/CD → Variables
- Adicione ANTHROPIC_API_KEY (mascarada, protegida conforme necessário)
Adicione um trabalho Claude ao .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Ajuste as regras para se adequar a como você deseja disparar o trabalho:
  # - execuções manuais
  # - eventos de merge request
  # - gatilhos web/API quando um comentário contém '@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:
    # Opcional: inicie um servidor GitLab MCP se sua configuração fornecer um
    - /bin/gitlab-mcp-server || true
    # Use variáveis AI_FLOW_* ao invocar via gatilhos web/API com payloads de contexto
    - 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

Após adicionar o trabalho e sua variável ANTHROPIC_API_KEY, teste executando o trabalho manualmente em CI/CD → Pipelines, ou dispare-o a partir de um MR para deixar Claude propor atualizações em um branch e abrir um MR se necessário.

Configuração manual (recomendada para produção)

Se você preferir uma configuração mais controlada ou precisar de provedores corporativos:

Configure o acesso do provedor:
- Claude API: Crie e armazene ANTHROPIC_API_KEY como uma variável de CI/CD mascarada
- Amazon Bedrock: Configure GitLab → AWS OIDC e crie uma função IAM para Bedrock
- Google Vertex AI: Configure Workload Identity Federation para GitLab → GCP
Adicione credenciais de projeto para operações da API GitLab:
- Use CI_JOB_TOKEN por padrão, ou crie um Project Access Token com escopo api
- Armazene como GITLAB_ACCESS_TOKEN (mascarado) se usar um PAT
Adicione o trabalho Claude ao .gitlab-ci.yml (veja exemplos abaixo)
(Opcional) Ative gatilhos orientados por menção:
- Adicione um webhook de projeto para "Comments (notes)" ao seu ouvinte de eventos (se você usar um)
- Faça o ouvinte chamar a API de gatilho de pipeline com variáveis como AI_FLOW_INPUT e AI_FLOW_CONTEXT quando um comentário contiver @claude

Exemplos de casos de uso

Transforme problemas em MRs

Em um comentário de problema:

@claude implement this feature based on the issue description

Claude analisa o problema e a base de código, escreve alterações em um branch e abre um MR para revisão.

Obtenha ajuda de implementação

Em uma discussão de MR:

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

Claude propõe alterações, adiciona código com cache apropriado e atualiza o MR.

Corrija bugs rapidamente

Em um comentário de problema ou MR:

@claude fix the TypeError in the user dashboard component

Claude localiza o bug, implementa uma correção e atualiza o branch ou abre um novo MR.

Usando com Amazon Bedrock & Google Vertex AI

Para ambientes corporativos, você pode executar Claude Code inteiramente em sua infraestrutura de nuvem com a mesma experiência do desenvolvedor.

Pré-requisitos

Antes de configurar Claude Code com Amazon Bedrock, você precisa de:

Uma conta AWS com acesso ao Amazon Bedrock para os modelos Claude desejados
GitLab configurado como um provedor de identidade OIDC no AWS IAM
Uma função IAM com permissões de Bedrock e uma política de confiança restrita ao seu projeto/refs do GitLab
Variáveis de CI/CD do GitLab para assunção de função:

AWS_ROLE_TO_ASSUME (ARN da função)
AWS_REGION (região do Bedrock)

Instruções de configuração

Configure AWS para permitir que trabalhos de CI do GitLab assumam uma função IAM via OIDC (sem chaves estáticas).

Configuração necessária:

Ative Amazon Bedrock e solicite acesso aos seus modelos Claude alvo
Crie um provedor OIDC do IAM para GitLab se ainda não estiver presente
Crie uma função IAM confiável pelo provedor OIDC do GitLab, restrita ao seu projeto e refs protegidos
Anexe permissões de privilégio mínimo para APIs de invocação do Bedrock

Valores necessários para armazenar em variáveis de CI/CD:

AWS_ROLE_TO_ASSUME
AWS_REGION

Adicione variáveis em Settings → CI/CD → Variables:

# Para Amazon Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

Use o exemplo de trabalho do Amazon Bedrock acima para trocar o token de trabalho do GitLab por credenciais AWS temporárias em tempo de execução.

Pré-requisitos

Antes de configurar Claude Code com Google Vertex AI, você precisa de:

Um projeto Google Cloud com:

Vertex AI API habilitada
Workload Identity Federation configurada para confiar no OIDC do GitLab

Uma conta de serviço dedicada com apenas as funções Vertex AI necessárias
Variáveis de CI/CD do GitLab para WIF:

GCP_WORKLOAD_IDENTITY_PROVIDER (nome completo do recurso)
GCP_SERVICE_ACCOUNT (email da conta de serviço)

Instruções de configuração

Configure Google Cloud para permitir que trabalhos de CI do GitLab representem uma conta de serviço via Workload Identity Federation.

Configuração necessária:

Ative IAM Credentials API, STS API e Vertex AI API
Crie um Workload Identity Pool e provedor para OIDC do GitLab
Crie uma conta de serviço dedicada com funções Vertex AI
Conceda ao principal WIF permissão para representar a conta de serviço

Valores necessários para armazenar em variáveis de CI/CD:

GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT

Adicione variáveis em Settings → CI/CD → Variables:

# Para Google Vertex AI:
- GCP_WORKLOAD_IDENTITY_PROVIDER
- GCP_SERVICE_ACCOUNT
- CLOUD_ML_REGION (por exemplo, us-east5)

Use o exemplo de trabalho do Google Vertex AI acima para autenticar sem armazenar chaves.

Exemplos de configuração

Abaixo estão trechos prontos para usar que você pode adaptar ao seu pipeline.

.gitlab-ci.yml básico (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 usará ANTHROPIC_API_KEY das variáveis de CI/CD

Exemplo de trabalho Amazon Bedrock (OIDC)

Pré-requisitos:

Amazon Bedrock habilitado com acesso ao seu modelo Claude escolhido
OIDC do GitLab configurado no AWS com uma função que confia no seu projeto e refs do GitLab
Função IAM com permissões de Bedrock (privilégio mínimo recomendado)

Variáveis de CI/CD necessárias:

AWS_ROLE_TO_ASSUME: ARN da função IAM para acesso ao Bedrock
AWS_REGION: Região do Bedrock (por exemplo, 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
    # Troque o token OIDC do GitLab por credenciais 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"

Exemplo de trabalho Google Vertex AI (Workload Identity Federation)

Pré-requisitos:

Vertex AI API habilitada em seu projeto GCP
Workload Identity Federation configurada para confiar no OIDC do GitLab
Uma conta de serviço com permissões Vertex AI

Variáveis de CI/CD necessárias:

GCP_WORKLOAD_IDENTITY_PROVIDER: Nome completo do recurso do provedor
GCP_SERVICE_ACCOUNT: Email da conta de serviço
CLOUD_ML_REGION: Região do Vertex (por exemplo, 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
    # Autentique no Google Cloud via WIF (sem chaves baixadas)
    - >
      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"

Melhores práticas

Configuração CLAUDE.md

Crie um arquivo CLAUDE.md na raiz do repositório para definir padrões de codificação, critérios de revisão e regras específicas do projeto. Claude lê este arquivo durante as execuções e segue suas convenções ao propor alterações.

Considerações de segurança

Nunca confirme chaves de API ou credenciais de nuvem em seu repositório. Sempre use variáveis de CI/CD do GitLab:

Adicione ANTHROPIC_API_KEY como uma variável mascarada (e proteja-a se necessário)
Use OIDC específico do provedor onde possível (sem chaves de longa duração)
Limite permissões de trabalho e saída de rede
Revise os MRs do Claude como qualquer outro colaborador

Otimizando desempenho

Mantenha CLAUDE.md focado e conciso
Forneça descrições claras de problema/MR para reduzir iterações
Configure timeouts de trabalho sensatos para evitar execuções descontroladas
Cache npm e instalações de pacotes em executores onde possível

Custos de CI

Ao usar Claude Code com GitLab CI/CD, esteja ciente dos custos associados:

Tempo do GitLab Runner:
- Claude é executado em seus executores GitLab e consome minutos de computação
- Consulte a cobrança de executor do seu plano GitLab para detalhes
Custos de API:
- Cada interação do Claude consome tokens com base no tamanho do prompt e resposta
- O uso de tokens varia pela complexidade da tarefa e tamanho da base de código
- Consulte Preços da Anthropic para detalhes
Dicas de otimização de custos:
- Use comandos @claude específicos para reduzir turnos desnecessários
- Defina valores apropriados de max_turns e timeout de trabalho
- Limite concorrência para controlar execuções paralelas

Segurança e governança

Cada trabalho é executado em um contêiner isolado com acesso de rede restrito
As alterações do Claude fluem através de MRs para que os revisores vejam cada diff
Regras de proteção de branch e aprovação se aplicam ao código gerado por IA
Claude Code usa permissões com escopo de workspace para restringir gravações
Os custos permanecem sob seu controle porque você traz suas próprias credenciais de provedor

Solução de problemas

Claude não responde aos comandos @claude

Verifique se seu pipeline está sendo disparado (manualmente, evento de MR ou via ouvinte de nota/webhook)
Certifique-se de que as variáveis de CI/CD (ANTHROPIC_API_KEY ou configurações de provedor de nuvem) estão presentes e desmascaradas
Verifique se o comentário contém @claude (não /claude) e se seu gatilho de menção está configurado

O trabalho não consegue escrever comentários ou abrir MRs

Certifique-se de que CI_JOB_TOKEN tem permissões suficientes para o projeto, ou use um Project Access Token com escopo api
Verifique se a ferramenta mcp__gitlab está habilitada em --allowedTools
Confirme se o trabalho é executado no contexto do MR ou tem contexto suficiente via variáveis AI_FLOW_*

Erros de autenticação

Para Claude API: Confirme que ANTHROPIC_API_KEY é válida e não expirou
Para Bedrock/Vertex: Verifique configuração de OIDC/WIF, representação de função e nomes de segredos; confirme disponibilidade de região e modelo

Configuração avançada

Parâmetros e variáveis comuns

Claude Code suporta estas entradas comumente usadas:

prompt / prompt_file: Forneça instruções inline (-p) ou via arquivo
max_turns: Limite o número de iterações de ida e volta
timeout_minutes: Limite o tempo total de execução
ANTHROPIC_API_KEY: Necessário para Claude API (não usado para Bedrock/Vertex)
Ambiente específico do provedor: AWS_REGION, variáveis de projeto/região para Vertex

Personalizando o comportamento do Claude

Você pode guiar Claude de duas formas principais:

CLAUDE.md: Defina padrões de codificação, requisitos de segurança e convenções de projeto. Claude lê isso durante as execuções e segue suas regras.
Prompts personalizados: Passe instruções específicas da tarefa via prompt/prompt_file no trabalho. Use prompts diferentes para trabalhos diferentes (por exemplo, revisão, implementação, refatoração).

gitlab-ci-cd.md +85 −29

16 Esta integração é construída sobre o [Claude Code CLI e Agent SDK](/pt/agent-sdk/overview), permitindo o uso programático do Claude em seus trabalhos de CI/CD e fluxos de trabalho de automação personalizados.16 Esta integração é construída sobre o [Claude Code CLI e Agent SDK](/pt/agent-sdk/overview), permitindo o uso programático do Claude em seus trabalhos de CI/CD e fluxos de trabalho de automação personalizados.

17</Note>17</Note>

18 18

~~19## Por que usar Claude Code com GitLab?~~19<h2 id="why-use-claude-code-with-gitlab">

20 Por que usar Claude Code com GitLab?

21</h2>

20 22

21* **Criação instantânea de MR**: Descreva o que você precisa, e Claude propõe um MR completo com alterações e explicação23* **Criação instantânea de MR**: Descreva o que você precisa, e Claude propõe um MR completo com alterações e explicação

22* **Implementação automatizada**: Transforme problemas em código funcional com um único comando ou menção24* **Implementação automatizada**: Transforme problemas em código funcional com um único comando ou menção

25* **Pronto para empresas**: Escolha Claude API, Amazon Bedrock ou Google Vertex AI para atender às necessidades de residência de dados e compras27* **Pronto para empresas**: Escolha Claude API, Amazon Bedrock ou Google Vertex AI para atender às necessidades de residência de dados e compras

26* **Seguro por padrão**: Executa em seus executores GitLab com sua proteção de branch e aprovações28* **Seguro por padrão**: Executa em seus executores GitLab com sua proteção de branch e aprovações

27 29

~~28## Como funciona~~30<h2 id="how-it-works">

31 Como funciona

32</h2>

29 33

30Claude Code usa GitLab CI/CD para executar tarefas de IA em trabalhos isolados e confirmar resultados de volta via MRs:34Claude Code usa GitLab CI/CD para executar tarefas de IA em trabalhos isolados e confirmar resultados de volta via MRs:

31 35

40 44

41Escolha endpoints regionais para reduzir latência e atender aos requisitos de soberania de dados enquanto usa acordos de nuvem existentes.45Escolha endpoints regionais para reduzir latência e atender aos requisitos de soberania de dados enquanto usa acordos de nuvem existentes.

42 46

~~43## O que Claude pode fazer?~~47<h2 id="what-can-claude-do">

48 O que Claude pode fazer?

49</h2>

44 50

45Claude Code permite fluxos de trabalho poderosos de CI/CD que transformam a forma como você trabalha com código:51Claude Code permite fluxos de trabalho poderosos de CI/CD que transformam a forma como você trabalha com código:

46 52

50* Corrigir bugs e regressões identificados por testes ou comentários56* Corrigir bugs e regressões identificados por testes ou comentários

51* Responder a comentários de acompanhamento para iterar sobre as alterações solicitadas57* Responder a comentários de acompanhamento para iterar sobre as alterações solicitadas

52 58

~~53## Configuração~~59<h2 id="setup">

60 Configuração

61</h2>

54 62

~~55### Configuração rápida~~63<h3 id="quick-setup">

64 Configuração rápida

65</h3>

56 66

57A forma mais rápida de começar é adicionar um trabalho mínimo ao seu `.gitlab-ci.yml` e definir sua chave de API como uma variável mascarada.67A forma mais rápida de começar é adicionar um trabalho mínimo ao seu `.gitlab-ci.yml` e definir sua chave de API como uma variável mascarada.

58 68

98Após adicionar o trabalho e sua variável `ANTHROPIC_API_KEY`, teste executando o trabalho manualmente em **CI/CD** → **Pipelines**, ou dispare-o a partir de um MR para deixar Claude propor atualizações em um branch e abrir um MR se necessário.108Após adicionar o trabalho e sua variável `ANTHROPIC_API_KEY`, teste executando o trabalho manualmente em **CI/CD** → **Pipelines**, ou dispare-o a partir de um MR para deixar Claude propor atualizações em um branch e abrir um MR se necessário.

99 109

100<Note>110<Note>

101 Para executar no Amazon Bedrock ou Google Vertex AI em vez da Claude API, consulte a seção [Usando com Amazon Bedrock & Google Vertex AI](#usando-com-amazon-bedrock--google-vertex-ai) abaixo para configuração de autenticação e ambiente.111 Para executar no Amazon Bedrock ou Google Vertex AI em vez da Claude API, consulte a seção [Usando com Amazon Bedrock & Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) abaixo para configuração de autenticação e ambiente.

102</Note>112</Note>

103 113

104### Configuração manual (recomendada para produção)114<h3 id="manual-setup-recommended-for-production">

115 Configuração manual (recomendada para produção)

116</h3>

105 117

106Se você preferir uma configuração mais controlada ou precisar de provedores corporativos:118Se você preferir uma configuração mais controlada ou precisar de provedores corporativos:

107 119

120 * Adicione um webhook de projeto para "Comments (notes)" ao seu ouvinte de eventos (se você usar um)132 * Adicione um webhook de projeto para "Comments (notes)" ao seu ouvinte de eventos (se você usar um)

121 * Faça o ouvinte chamar a API de gatilho de pipeline com variáveis como `AI_FLOW_INPUT` e `AI_FLOW_CONTEXT` quando um comentário contiver `@claude`133 * Faça o ouvinte chamar a API de gatilho de pipeline com variáveis como `AI_FLOW_INPUT` e `AI_FLOW_CONTEXT` quando um comentário contiver `@claude`

122 134

123## Exemplos de casos de uso135<h2 id="example-use-cases">

136 Exemplos de casos de uso

137</h2>

124 138

125### Transforme problemas em MRs139<h3 id="turn-issues-into-mrs">

140 Transforme problemas em MRs

141</h3>

126 142

127Em um comentário de problema:143Em um comentário de problema:

128 144

132 148

133Claude analisa o problema e a base de código, escreve alterações em um branch e abre um MR para revisão.149Claude analisa o problema e a base de código, escreve alterações em um branch e abre um MR para revisão.

134 150

135### Obtenha ajuda de implementação151<h3 id="get-implementation-help">

152 Obtenha ajuda de implementação

153</h3>

136 154

137Em uma discussão de MR:155Em uma discussão de MR:

138 156

142 160

143Claude propõe alterações, adiciona código com cache apropriado e atualiza o MR.161Claude propõe alterações, adiciona código com cache apropriado e atualiza o MR.

144 162

145### Corrija bugs rapidamente163<h3 id="fix-bugs-quickly">

164 Corrija bugs rapidamente

165</h3>

146 166

147Em um comentário de problema ou MR:167Em um comentário de problema ou MR:

148 168

152 172

153Claude localiza o bug, implementa uma correção e atualiza o branch ou abre um novo MR.173Claude localiza o bug, implementa uma correção e atualiza o branch ou abre um novo MR.

154 174

155## Usando com Amazon Bedrock & Google Vertex AI175<h2 id="using-with-amazon-bedrock--google-vertex-ai">

176 Usando com Amazon Bedrock & Google Vertex AI

177</h2>

156 178

157Para ambientes corporativos, você pode executar Claude Code inteiramente em sua infraestrutura de nuvem com a mesma experiência do desenvolvedor.179Para ambientes corporativos, você pode executar Claude Code inteiramente em sua infraestrutura de nuvem com a mesma experiência do desenvolvedor.

158 180

238 </Tab>260 </Tab>

239</Tabs>261</Tabs>

240 262

241## Exemplos de configuração263<h2 id="configuration-examples">

264 Exemplos de configuração

265</h2>

242 266

243Abaixo estão trechos prontos para usar que você pode adaptar ao seu pipeline.267Abaixo estão trechos prontos para usar que você pode adaptar ao seu pipeline.

244 268

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

270 .gitlab-ci.yml básico (Claude API)

271</h3>

246 272

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

248stages:274stages:

271 # Claude Code usará ANTHROPIC_API_KEY das variáveis de CI/CD297 # Claude Code usará ANTHROPIC_API_KEY das variáveis de CI/CD

272```298```

273 299

274### Exemplo de trabalho Amazon Bedrock (OIDC)300<h3 id="amazon-bedrock-job-example-oidc">

301 Exemplo de trabalho Amazon Bedrock (OIDC)

302</h3>

275 303

276**Pré-requisitos:**304**Pré-requisitos:**

277 305

322 IDs de modelo para Bedrock incluem prefixos específicos de região (por exemplo, `us.anthropic.claude-sonnet-4-6`). Passe o modelo desejado via sua configuração de trabalho ou prompt se seu fluxo de trabalho suportar.350 IDs de modelo para Bedrock incluem prefixos específicos de região (por exemplo, `us.anthropic.claude-sonnet-4-6`). Passe o modelo desejado via sua configuração de trabalho ou prompt se seu fluxo de trabalho suportar.

323</Note>351</Note>

324 352

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

354 Exemplo de trabalho Google Vertex AI (Workload Identity Federation)

355</h3>

326 356

327**Pré-requisitos:**357**Pré-requisitos:**

328 358

375 Com Workload Identity Federation, você não precisa armazenar chaves de conta de serviço. Use condições de confiança específicas do repositório e contas de serviço com privilégio mínimo.405 Com Workload Identity Federation, você não precisa armazenar chaves de conta de serviço. Use condições de confiança específicas do repositório e contas de serviço com privilégio mínimo.

376</Note>406</Note>

377 407

378## Melhores práticas408<h2 id="best-practices">

409 Melhores práticas

410</h2>

379 411

380### Configuração CLAUDE.md412<h3 id="claude-md-configuration">

413 Configuração CLAUDE.md

414</h3>

381 415

382Crie um arquivo `CLAUDE.md` na raiz do repositório para definir padrões de codificação, critérios de revisão e regras específicas do projeto. Claude lê este arquivo durante as execuções e segue suas convenções ao propor alterações.416Crie um arquivo `CLAUDE.md` na raiz do repositório para definir padrões de codificação, critérios de revisão e regras específicas do projeto. Claude lê este arquivo durante as execuções e segue suas convenções ao propor alterações.

383 417

384### Considerações de segurança418<h3 id="security-considerations">

419 Considerações de segurança

420</h3>

385 421

386**Nunca confirme chaves de API ou credenciais de nuvem em seu repositório**. Sempre use variáveis de CI/CD do GitLab:422**Nunca confirme chaves de API ou credenciais de nuvem em seu repositório**. Sempre use variáveis de CI/CD do GitLab:

387 423

390* Limite permissões de trabalho e saída de rede426* Limite permissões de trabalho e saída de rede

391* Revise os MRs do Claude como qualquer outro colaborador427* Revise os MRs do Claude como qualquer outro colaborador

392 428

393### Otimizando desempenho429<h3 id="optimizing-performance">

430 Otimizando desempenho

431</h3>

394 432

395* Mantenha `CLAUDE.md` focado e conciso433* Mantenha `CLAUDE.md` focado e conciso

396* Forneça descrições claras de problema/MR para reduzir iterações434* Forneça descrições claras de problema/MR para reduzir iterações

397* Configure timeouts de trabalho sensatos para evitar execuções descontroladas435* Configure timeouts de trabalho sensatos para evitar execuções descontroladas

398* Cache npm e instalações de pacotes em executores onde possível436* Cache npm e instalações de pacotes em executores onde possível

399 437

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

439 Custos de CI

440</h3>

401 441

402Ao usar Claude Code com GitLab CI/CD, esteja ciente dos custos associados:442Ao usar Claude Code com GitLab CI/CD, esteja ciente dos custos associados:

403 443

415 * Defina valores apropriados de `max_turns` e timeout de trabalho455 * Defina valores apropriados de `max_turns` e timeout de trabalho

416 * Limite concorrência para controlar execuções paralelas456 * Limite concorrência para controlar execuções paralelas

417 457

418## Segurança e governança458<h2 id="security-and-governance">

459 Segurança e governança

460</h2>

419 461

420* Cada trabalho é executado em um contêiner isolado com acesso de rede restrito462* Cada trabalho é executado em um contêiner isolado com acesso de rede restrito

421* As alterações do Claude fluem através de MRs para que os revisores vejam cada diff463* As alterações do Claude fluem através de MRs para que os revisores vejam cada diff

423* Claude Code usa permissões com escopo de workspace para restringir gravações465* Claude Code usa permissões com escopo de workspace para restringir gravações

424* Os custos permanecem sob seu controle porque você traz suas próprias credenciais de provedor466* Os custos permanecem sob seu controle porque você traz suas próprias credenciais de provedor

425 467

426## Solução de problemas468<h2 id="troubleshooting">

469 Solução de problemas

470</h2>

427 471

428### Claude não responde aos comandos @claude472<h3 id="claude-not-responding-to-claude-commands">

473 Claude não responde aos comandos @claude

474</h3>

429 475

430* Verifique se seu pipeline está sendo disparado (manualmente, evento de MR ou via ouvinte de nota/webhook)476* Verifique se seu pipeline está sendo disparado (manualmente, evento de MR ou via ouvinte de nota/webhook)

431* Certifique-se de que as variáveis de CI/CD (`ANTHROPIC_API_KEY` ou configurações de provedor de nuvem) estão presentes e desmascaradas477* Certifique-se de que as variáveis de CI/CD (`ANTHROPIC_API_KEY` ou configurações de provedor de nuvem) estão presentes e desmascaradas

432* Verifique se o comentário contém `@claude` (não `/claude`) e se seu gatilho de menção está configurado478* Verifique se o comentário contém `@claude` (não `/claude`) e se seu gatilho de menção está configurado

433 479

434### O trabalho não consegue escrever comentários ou abrir MRs480<h3 id="job-can’t-write-comments-or-open-mrs">

481 O trabalho não consegue escrever comentários ou abrir MRs

482</h3>

435 483

436* Certifique-se de que `CI_JOB_TOKEN` tem permissões suficientes para o projeto, ou use um Project Access Token com escopo `api`484* Certifique-se de que `CI_JOB_TOKEN` tem permissões suficientes para o projeto, ou use um Project Access Token com escopo `api`

437* Verifique se a ferramenta `mcp__gitlab` está habilitada em `--allowedTools`485* Verifique se a ferramenta `mcp__gitlab` está habilitada em `--allowedTools`

438* Confirme se o trabalho é executado no contexto do MR ou tem contexto suficiente via variáveis `AI_FLOW_*`486* Confirme se o trabalho é executado no contexto do MR ou tem contexto suficiente via variáveis `AI_FLOW_*`

439 487

440### Erros de autenticação488<h3 id="authentication-errors">

489 Erros de autenticação

490</h3>

441 491

442* **Para Claude API**: Confirme que `ANTHROPIC_API_KEY` é válida e não expirou492* **Para Claude API**: Confirme que `ANTHROPIC_API_KEY` é válida e não expirou

443* **Para Bedrock/Vertex**: Verifique configuração de OIDC/WIF, representação de função e nomes de segredos; confirme disponibilidade de região e modelo493* **Para Bedrock/Vertex**: Verifique configuração de OIDC/WIF, representação de função e nomes de segredos; confirme disponibilidade de região e modelo

444 494

445## Configuração avançada495<h2 id="advanced-configuration">

496 Configuração avançada

497</h2>

446 498

447### Parâmetros e variáveis comuns499<h3 id="common-parameters-and-variables">

500 Parâmetros e variáveis comuns

501</h3>

448 502

449Claude Code suporta estas entradas comumente usadas:503Claude Code suporta estas entradas comumente usadas:

450 504

458 Sinalizadores e parâmetros exatos podem variar por versão de `@anthropic-ai/claude-code`. Execute `claude --help` em seu trabalho para ver as opções suportadas.512 Sinalizadores e parâmetros exatos podem variar por versão de `@anthropic-ai/claude-code`. Execute `claude --help` em seu trabalho para ver as opções suportadas.

459</Note>513</Note>

460 514

461### Personalizando o comportamento do Claude515<h3 id="customizing-claude’s-behavior">

516 Personalizando o comportamento do Claude

517</h3>

462 518

463Você pode guiar Claude de duas formas principais:519Você pode guiar Claude de duas formas principais:

464 520

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

Claude Code GitLab CI/CD

Por que usar Claude Code com GitLab?

Como funciona

O que Claude pode fazer?

Configuração

Configuração rápida

Configuração manual (recomendada para produção)

Exemplos de casos de uso

Transforme problemas em MRs

Obtenha ajuda de implementação

Corrija bugs rapidamente

Usando com Amazon Bedrock & Google Vertex AI

Pré-requisitos

Instruções de configuração

Pré-requisitos

Instruções de configuração

Exemplos de configuração

.gitlab-ci.yml básico (Claude API)

Exemplo de trabalho Amazon Bedrock (OIDC)

Exemplo de trabalho Google Vertex AI (Workload Identity Federation)

Melhores práticas

Configuração CLAUDE.md

Considerações de segurança

Otimizando desempenho

Custos de CI

Segurança e governança

Solução de problemas

Claude não responde aos comandos @claude

O trabalho não consegue escrever comentários ou abrir MRs

Erros de autenticação

Configuração avançada

Parâmetros e variáveis comuns

Personalizando o comportamento do Claude