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 mascarada de CI/CD
• 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:

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:

   • Anthropic 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 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 poderosos de CI/CD 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 API como uma variável mascarada.

1. Adicione uma variável mascarada de CI/CD

   • 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

Após adicionar o job e sua variável ANTHROPIC_API_KEY, teste executando o job manualmente de CI/CD → Pipelines, ou acione-o 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 empresariais:

1. Configure acesso ao provedor:

   • Anthropic API: Crie e armazene ANTHROPIC_API_KEY como uma variável mascarada de CI/CD
   • 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 do 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 implement this feature based on the issue description

Claude analisa a issue e codebase, 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 suggest a concrete approach to cache the results of this API call

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

# Para AWS Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

# 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

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

Pré-requisitos:

• Amazon Bedrock habilitado com acesso aos seus modelos Claude escolhidos
• 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)

Variáveis de CI/CD necessárias:

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

Pré-requisitos:

• API Vertex AI habilitada em 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:-'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 execuções e segue suas convenções ao propor mudanças.

​

Considerações de segurança

Nunca confirme chaves 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 job e saída 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 do 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 respondendo a comandos @claude

• Verifique se seu pipeline está sendo acionado (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 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 essas 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 o tempo total de execução
• ANTHROPIC_API_KEY: Necessário para a Anthropic 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

Você pode guiar Claude de duas maneiras principais:

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