SpyBara
Go Premium

gitlab-ci-cd.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 136 additions and 171 deletions.

2026
Wed 9 22:58

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 Cloud's Agent Platform 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:

  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)
    • Amazon Bedrock (acesso baseado em IAM, opções entre regiões)
    • Google Cloud's Agent Platform (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.

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?

Em um pipeline do GitLab, Claude Code pode:

  • Criar e atualizar MRs a partir de descrições ou comentários de issues
  • Analisar regressões de desempenho e propor otimizações
  • Implementar recursos diretamente em uma branch, depois abrir uma 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 job mínimo ao seu .gitlab-ci.yml e definir sua chave de API como uma variável mascarada.

  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 as regras para se adequar a como você deseja disparar o job:
  # - execuções manuais
  # - eventos de merge request
  # - acionadores 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
    # O instalador coloca claude em ~/.local/bin, que não está no PATH nesta imagem
    - export PATH="$HOME/.local/bin:$PATH"
  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 acionadores 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 em CI/CD → Pipelines, ou dispare-o a partir de um MR para deixar Claude propor atualizações em uma branch e abrir um MR se necessário.

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

  1. Configure o acesso ao provedor:

    • Claude API: Crie e armazene ANTHROPIC_API_KEY como uma variável CI/CD mascarada
    • Amazon Bedrock: Configure GitLab → AWS OIDC e crie uma função IAM para Amazon Bedrock
    • Agent Platform do Google Cloud: Configure Workload Identity Federation for 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 (mascarada) se usar um PAT

  3. Adicione o job Claude ao .gitlab-ci.yml: use o job Quick setup para a Claude API, ou um job de provedor de Configuration examples

  4. (Opcional) Ative acionadores acionados 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 acionamento de pipeline com variáveis como AI_FLOW_INPUT e AI_FLOW_CONTEXT quando um comentário contiver @claude

Exemplos de casos de uso

Transformar 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 uma ramificação e abre um MR para revisão.

Obter ajuda com 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.

Corrigir 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 a ramificação ou abre um novo MR.

Usando com Amazon Bedrock e Google Cloud

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 Amazon Bedrock, você precisa de:

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

Instruções de configuração

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

Configuração obrigatória:

  1. Ative o Amazon Bedrock e solicite acesso aos seus modelos Claude de destino
  2. Crie um provedor OIDC do IAM para GitLab se ainda não estiver presente
  3. Crie uma função IAM confiável pelo provedor OIDC do GitLab, restrita ao seu projeto e refs protegidas
  4. Anexe permissões de menor privilégio para APIs de invocação do Amazon Bedrock

Use o exemplo de trabalho do Amazon Bedrock para trocar o token OIDC do trabalho 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.

Exemplo de job do Amazon Bedrock (OIDC)

Pré-requisitos:

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

Variáveis CI/CD obrigatórias:

  • AWS_ROLE_TO_ASSUME: ARN da função IAM para acesso ao Amazon Bedrock
  • AWS_REGION: região do Amazon Bedrock (por exemplo, us-west-2)

O GitLab cria o token OIDC do job a partir do bloco id_tokens: e o expõe como GITLAB_OIDC_TOKEN. Defina aud para o valor de audiência que você configurou no provedor de identidade OIDC do IAM na AWS, por exemplo, a URL da sua instância GitLab.

stages:
  - ai

claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apk add --no-cache bash curl jq git aws-cli
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Exchange the job's OIDC token for AWS credentials
    - export AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/oidc_token"
    - printf "%s" "$GITLAB_OIDC_TOKEN" > "$AWS_WEB_IDENTITY_TOKEN_FILE"
    - >
      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"
    CLAUDE_CODE_USE_BEDROCK: "1"

Exemplo de job do Agent Platform (Workload Identity Federation)

Pré-requisitos:

  • API do Agent Platform do Google Cloud habilitada no seu projeto GCP
  • Workload Identity Federation configurada para confiar no OIDC do GitLab
  • Uma conta de serviço com permissões do Agent Platform do Google Cloud

Variáveis CI/CD obrigatórias:

  • GCP_WORKLOAD_IDENTITY_PROVIDER: nome do recurso do provedor sem o prefixo //iam.googleapis.com/, como projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
  • GCP_SERVICE_ACCOUNT: email da conta de serviço
  • GCP_PROJECT_ID: ID do projeto Google Cloud
  • CLOUD_ML_REGION: região do Agent Platform do Google Cloud (por exemplo, us-east5)

O GitLab cria o token OIDC do job a partir do bloco id_tokens: e o expõe como GITLAB_OIDC_TOKEN. Defina aud para o valor de audiência que você configurou no provedor do Workload Identity Pool, por exemplo, a URL da sua instância GitLab. O job escreve o token em um arquivo, e a entrada credential_source da configuração de credenciais diz às bibliotecas de autenticação do Google para lê-lo de lá. Definir GOOGLE_APPLICATION_CREDENTIALS para o arquivo de configuração de credenciais o torna disponível para Claude Code através de Application Default Credentials.

stages:
  - ai

claude-vertex:
  stage: ai
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  before_script:
    - apt-get update && apt-get install -y git && apt-get clean
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer places claude in ~/.local/bin, which isn't on PATH in this image
    - export PATH="$HOME/.local/bin:$PATH"
    # Write the job's OIDC token where credential_source expects it
    - printf "%s" "$GITLAB_OIDC_TOKEN" > /tmp/oidc_token
    # Write the WIF credential configuration to a file (no downloaded keys)
    - |
      cat > /tmp/cred.json <<EOF
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/${GCP_WORKLOAD_IDENTITY_PROVIDER}",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "/tmp/oidc_token"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken"
      }
      EOF
    # Expose the credentials to Claude Code via Application Default Credentials
    - export GOOGLE_APPLICATION_CREDENTIALS=/tmp/cred.json
    # Authenticate the gcloud CLI with the same credential configuration
    - gcloud auth login --cred-file=/tmp/cred.json
    - gcloud config set project "$GCP_PROJECT_ID"
  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"
    CLAUDE_CODE_USE_VERTEX: "1"
    ANTHROPIC_VERTEX_PROJECT_ID: "$GCP_PROJECT_ID"

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 faça commit de chaves de API ou credenciais de nuvem no seu repositório. Sempre use variáveis de GitLab CI/CD:

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

Otimizando o desempenho

  • Mantenha CLAUDE.md focado e conciso
  • Forneça descrições claras de issue/MR para reduzir iterações
  • Armazene em cache npm e instalações de pacotes em runners quando 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 runners do GitLab e consome minutos de computação
    • Consulte os detalhes de faturamento do runner do seu plano GitLab

  • Custos de API:

    • Cada interação do Claude consome tokens com base no tamanho do prompt e da resposta
    • O uso de tokens varia de acordo com a complexidade da tarefa e o 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 a concorrência para controlar execuções paralelas

Troubleshooting

Claude não responde aos comandos @claude

  • Verifique se seu pipeline está sendo acionado (manualmente, evento MR ou via listener de evento de nota/webhook)
  • Certifique-se de que suas variáveis ANTHROPIC_API_KEY ou do provedor de nuvem estão presentes
  • Verifique se o comentário contém @claude (não /claude) e se 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 se o job é 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 Amazon Bedrock ou Google Cloud's Agent Platform: Verifique a configuração OIDC/WIF, impersonação de função e nomes de segredos; confirme a disponibilidade de região e modelo

Configuração avançada

Parâmetros e variáveis comuns

Controle as execuções do Claude Code em seus jobs com esses sinalizadores CLI, palavras-chave do GitLab e variáveis:

  • -p: forneça instruções inline, por exemplo claude -p "Review this MR"
  • --max-turns: limite o número de iterações de ida e volta
  • timeout: limite o tempo total de execução do job com a palavra-chave timeout de nível de job do GitLab, por exemplo timeout: 30m
  • ANTHROPIC_API_KEY: obrigatório para a API Claude (não usado para Amazon Bedrock ou Agent Platform do Google Cloud)
  • Ambiente específico do provedor: AWS_REGION, variáveis de projeto/região para Agent Platform do Google Cloud

Personalizando o comportamento do Claude

Você pode orientar o Claude de duas maneiras principais:

  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 -p no job. Use prompts diferentes para jobs diferentes (por exemplo, review, implement, refactor).