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 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, AWS 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

1. 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.
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 entre regiões)
   • Google Vertex AI (nativo do GCP, Workload Identity Federation)
3. 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.

​

O que Claude pode fazer?

• 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

1. Adicione uma variável de CI/CD mascarada
   • Vá para Settings → CI/CD → Variables
   • Adicione ANTHROPIC_API_KEY (mascarada, protegida conforme necessário)
2. 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

​

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

1. Configure o acesso do provedor:
   • Claude API: Crie e armazene ANTHROPIC_API_KEY como uma variável de 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 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
3. Adicione o trabalho Claude ao .gitlab-ci.yml (veja exemplos abaixo)
4. (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

@claude implement this feature based on the issue description

​

Obtenha ajuda de implementação

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

​

Corrija 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

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

​

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

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

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

• 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

• 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

​

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

• 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

• 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

1. 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.
2. 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).