Claude Code GitLab CI/CD

Claude Code para GitLab CI/CD está atualmente em beta. Recursos e funcionalidades podem evoluir conforme refinamos a experiência.Esta integração é mantida pelo GitLab. Para suporte, veja a seguinte issue do GitLab.

Esta integração é construída sobre o Claude Code CLI e SDK, permitindo o uso programático do Claude em seus jobs de CI/CD e fluxos de trabalho de automação personalizados.

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 mudanças e explicação
Implementação automatizada: Transforme issues em código funcional com um único comando ou menção
Consciente do projeto: Claude segue suas diretrizes do CLAUDE.md e padrões de código existentes
Configuração simples: Adicione um job ao .gitlab-ci.yml e uma variável de CI/CD mascarada
Pronto para empresa: Escolha Anthropic API, AWS Bedrock, ou Google Vertex AI para atender necessidades de residência de dados e aquisição
Seguro por padrão: Executa em seus runners do GitLab com sua proteção de branch e aprovações

Como funciona

Claude Code usa GitLab CI/CD para executar tarefas de IA em jobs 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 uma issue, MR, ou thread de revisão). O job coleta contexto da thread e 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:
- Anthropic API (SaaS)
- AWS 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 executa em um contêiner com regras rígidas de rede e sistema de arquivos. Claude Code impõe permissões com escopo de workspace para restringir escritas. Toda mudança flui através de um MR para que revisores vejam o diff e aprovações ainda se apliquem.

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

O que Claude pode fazer?

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

Criar e atualizar MRs a partir de descrições de issues ou comentários
Analisar regressões de performance 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 mudanças solicitadas

Configuração

Configuração rápida

A maneira mais rápida de começar é adicionar um job 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 job Claude ao .gitlab-ci.yml

stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  # Ajuste regras para se adequar a como você quer disparar o job:
  # - 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
    - npm install -g @anthropic-ai/claude-code
  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:-'Revise este MR e implemente as mudanças solicitadas'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug

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

Para executar no AWS Bedrock ou Google Vertex AI em vez da Anthropic API, veja a seção Usando com AWS Bedrock & Google Vertex AI abaixo para configuração de autenticação e ambiente.

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

Se você prefere uma configuração mais controlada ou precisa de provedores empresariais:

Configure acesso ao provedor:
- Anthropic API: Crie e armazene ANTHROPIC_API_KEY como uma variável de CI/CD mascarada
- AWS Bedrock: Configure GitLab → AWS OIDC e crie um papel IAM para Bedrock
- Google Vertex AI: Configure Workload Identity Federation para GitLab → GCP
Adicione credenciais do 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 job Claude ao .gitlab-ci.yml (veja exemplos abaixo)
(Opcional) Habilite 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 contém @claude

Exemplos de casos de uso

Transformar issues em MRs

Em um comentário de issue:

@claude implemente este recurso baseado na descrição da issue

Claude analisa a issue e base de código, escreve mudanças em um branch, e abre um MR para revisão.

Obter ajuda de implementação

Em uma discussão de MR:

@claude sugira uma abordagem concreta para cachear os resultados desta chamada de API

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

Corrigir bugs rapidamente

Em um comentário de issue ou MR:

@claude corrija o TypeError no componente do dashboard do usuário

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

Usando com AWS Bedrock & Google Vertex AI

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

Pré-requisitos

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

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

Instruções de configuração

Configure AWS para permitir que jobs de CI GitLab assumam um papel IAM via OIDC (sem chaves estáticas).Configuração necessária:

Habilite Amazon Bedrock e solicite acesso aos seus modelos Claude alvo
Crie um provedor OIDC IAM para GitLab se ainda não estiver presente
Crie um papel IAM confiado pelo provedor OIDC GitLab, restrito ao seu projeto e refs protegidos
Anexe permissões de menor privilégio para APIs de invocação 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 AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

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

Exemplos de configuração

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

.gitlab-ci.yml básico (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:-'Resuma mudanças recentes e sugira melhorias'}"
      --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 job AWS Bedrock (OIDC)

Pré-requisitos:

Amazon Bedrock habilitado com acesso aos seus modelos Claude escolhidos
GitLab OIDC configurado no AWS com um papel que confia no seu projeto e refs GitLab
Papel IAM com permissões Bedrock (menor privilégio recomendado)

Variáveis de CI/CD necessárias:

AWS_ROLE_TO_ASSUME: ARN do papel IAM para acesso Bedrock
AWS_REGION: Região 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
    - npm install -g @anthropic-ai/claude-code
    # Troque token OIDC 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:-'Implemente as mudanças solicitadas e abra um MR'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    AWS_REGION: "us-west-2"

IDs de modelo para Bedrock incluem prefixos específicos de região e sufixos de versão (por exemplo, us.anthropic.claude-3-7-sonnet-20250219-v1:0). Passe o modelo desejado via sua configuração de job ou prompt se seu fluxo de trabalho suportar.

Exemplo de job Google Vertex AI (Workload Identity Federation)

Pré-requisitos:

API Vertex AI habilitada no seu projeto GCP
Workload Identity Federation configurado para confiar no OIDC 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 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 nodejs npm && apt-get clean
    - npm install -g @anthropic-ai/claude-code
    # 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:-'Revise e atualize código conforme solicitado'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug
  variables:
    CLOUD_ML_REGION: "us-east5"

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 de menor privilégio.

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 execuções e segue suas convenções ao propor mudanças.

Considerações de segurança

Nunca confirme chaves de API ou credenciais de nuvem no seu repositório! Sempre use variáveis de CI/CD 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 job e egresso de rede
Revise MRs do Claude como qualquer outro contribuidor

Otimizando performance

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

Custos de CI

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

Tempo de GitLab Runner:
- Claude executa em seus runners GitLab e consome minutos de computação
- Veja o faturamento de runner do seu plano GitLab para detalhes
Custos de API:
- Cada interação Claude consome tokens baseados no tamanho do prompt e resposta
- Uso de tokens varia por complexidade da tarefa e tamanho da base de código
- Veja preços 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 job
- Limite concorrência para controlar execuções paralelas

Segurança e governança

Cada job executa em um contêiner isolado com acesso de rede restrito
Mudanças do Claude fluem através de MRs para que revisores vejam cada diff
Regras de proteção de branch e aprovação se aplicam a código gerado por IA
Claude Code usa permissões com escopo de workspace para restringir escritas
Custos permanecem sob seu controle porque você traz suas próprias credenciais de provedor

Solução de problemas

Claude não respondendo a comandos @claude

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

Job 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 que o job executa no contexto do MR ou tem contexto suficiente via variáveis AI_FLOW_*

Erros de autenticação

Para Anthropic API: Confirme que ANTHROPIC_API_KEY é válida e não expirou
Para Bedrock/Vertex: Verifique configuração OIDC/WIF, personificação de papel, 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 um arquivo
max_turns: Limite o número de iterações de ida e volta
timeout_minutes: Limite tempo total de execução
ANTHROPIC_API_KEY: Necessária para a Anthropic API (não usada para Bedrock/Vertex)
Ambiente específico do provedor: AWS_REGION, variáveis de projeto/região para Vertex

Flags e parâmetros exatos podem variar por versão do @anthropic-ai/claude-code. Execute claude --help no seu job para ver opções suportadas.

Personalizando comportamento do Claude

Você pode guiar Claude de duas maneiras principais:

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

Primeiros passos

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

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

Transformar issues em MRs

Obter ajuda de implementação

Corrigir bugs rapidamente

Usando com AWS Bedrock & Google Vertex AI

Pré-requisitos

Instruções de configuração

Exemplos de configuração

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

Exemplo de job AWS Bedrock (OIDC)

Exemplo de job Google Vertex AI (Workload Identity Federation)

Melhores práticas

Configuração CLAUDE.md

Considerações de segurança

Otimizando performance

Custos de CI

Segurança e governança

Solução de problemas

Claude não respondendo a comandos @claude

Job não consegue escrever comentários ou abrir MRs

Erros de autenticação

Configuração avançada

Parâmetros e variáveis comuns

Personalizando comportamento do Claude

Primeiros passos

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

​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

​Transformar issues em MRs

​Obter ajuda de implementação

​Corrigir bugs rapidamente

​Usando com AWS Bedrock & Google Vertex AI

​Pré-requisitos

​Instruções de configuração

​Exemplos de configuração

​.gitlab-ci.yml básico (Anthropic API)

​Exemplo de job AWS Bedrock (OIDC)

​Exemplo de job Google Vertex AI (Workload Identity Federation)

​Melhores práticas

​Configuração CLAUDE.md

​Considerações de segurança

​Otimizando performance

​Custos de CI

​Segurança e governança

​Solução de problemas

​Claude não respondendo a comandos @claude

​Job não consegue escrever comentários ou abrir MRs

​Erros de autenticação

​Configuração avançada

​Parâmetros e variáveis comuns

​Personalizando comportamento do Claude

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

Transformar issues em MRs

Obter ajuda de implementação

Corrigir bugs rapidamente

Usando com AWS Bedrock & Google Vertex AI

Pré-requisitos

Instruções de configuração

Exemplos de configuração

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

Exemplo de job AWS Bedrock (OIDC)

Exemplo de job Google Vertex AI (Workload Identity Federation)

Melhores práticas

Configuração CLAUDE.md

Considerações de segurança

Otimizando performance

Custos de CI

Segurança e governança

Solução de problemas

Claude não respondendo a comandos @claude

Job não consegue escrever comentários ou abrir MRs

Erros de autenticação

Configuração avançada

Parâmetros e variáveis comuns

Personalizando comportamento do Claude