Claude Code 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 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 CI/CD mascarada
• Pronto para empresa: Escolha Claude 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

1. 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.
2. Abstração de provedor: Use o provedor que se adequa ao seu ambiente:
   • Claude API (SaaS)
   • AWS Bedrock (acesso baseado em IAM, opções cross-region)
   • Google Vertex AI (nativo do GCP, Workload Identity Federation)
3. Execução em sandbox: Cada interação executa 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 escritas. Toda mudança flui através de um MR para que revisores vejam o diff e aprovações ainda se apliquem.

​

O que Claude pode fazer?

• 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

1. Adicione uma variável CI/CD mascarada
   • Vá para Settings → CI/CD → Variables
   • Adicione ANTHROPIC_API_KEY (mascarada, protegida conforme necessário)
2. 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 acionar 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:-'Review this MR and implement the requested changes'}"
      --permission-mode acceptEdits
      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
      --debug

​

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

1. Configure acesso ao provedor:
   • Claude API: Crie e armazene ANTHROPIC_API_KEY como uma variável CI/CD mascarada
   • AWS Bedrock: Configure GitLab → AWS OIDC e crie uma função IAM para Bedrock
   • Google Vertex AI: Configure Workload Identity Federation para GitLab → GCP
2. 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
3. Adicione o job Claude ao .gitlab-ci.yml (veja exemplos abaixo)
4. (Opcional) Habilite gatilhos orientados por menção:
   • Adicione um webhook de projeto para “Comments (notes)” ao seu listener de eventos (se você usar um)
   • Faça o listener 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

​

Casos de uso de exemplo

​

Transformar issues em MRs

@claude implement this feature based on the issue description

​

Obter ajuda de implementação

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

​

Corrigir bugs rapidamente

@claude fix the TypeError in the user dashboard component

​

Usando com AWS Bedrock & Google Vertex AI

# Para AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

​

Exemplos de configuração

​

.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
    - npm install -g @anthropic-ai/claude-code
  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 CI/CD

​

Exemplo de job AWS Bedrock (OIDC)

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

• AWS_ROLE_TO_ASSUME: ARN da função 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:-'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 job Google Vertex AI (Workload Identity Federation)

• 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

• 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:-'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

​

Considerações de segurança

• 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

• 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 codebase
  • 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 ao 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 responde a comandos @claude

• Verifique se seu pipeline está sendo acionado (manualmente, evento MR, ou via listener/webhook de evento de nota)
• Certifique-se de que variáveis 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 Claude API: Confirme que ANTHROPIC_API_KEY é válida e não expirou
• Para Bedrock/Vertex: Verifique configuração OIDC/WIF, personificaçã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

• 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 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 comportamento do Claude

1. CLAUDE.md: Defina padrões de codificação, requisitos de segurança, e convenções de projeto. Claude lê isso durante execuções e segue suas regras.
2. 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).