Claude Code e o GitLab: três fluxos de trabalho que realmente entregam

Os desenvolvedores adoram o Claude Code porque utilizá-lo é como programar em dupla com um engenheiro sênior direto no terminal ou na IDE: ele ajuda você a entender código desconhecido, propor correções e estruturar novos recursos rapidamente.

Contudo, há um padrão que vale observar: quanto melhores ficam as ferramentas de programação com agentes de IA para escrever código, mais o restante do ciclo de vida do software luta para acompanhar o ritmo. O backlog de bugs cresce. As taxas de falha nos pipelines crescem e as vulnerabilidades de segurança se acumulam mais rápido do que os times conseguem classificá-las. Isso mostra que programar e entregar um software não são a mesma coisa, e essa diferença entre os dois é real.

É neste ponto que o GitLab entra para acelerar tudo o que vem depois do Claude Code no restante do ciclo de vida do software: CI/CD, verificação de segurança, revisão de código e aprovações, tudo em um só lugar, com um fluxo auditável.

Este tutorial apresenta três cenários nos quais o Claude Code avança rápido na base de código, enquanto o GitLab cuida de tudo o que transforma esse código em uma mudança certificada e entregue:

• Corrija um bug em C++ com o Claude Code e deixe que o GitLab CI/CD, a verificação de segurança e o Duo Code Review sigam a partir daí.
• Adicione contexto do GitLab via MCP para que o Claude trabalhe a partir do tíquete real, e não apenas dos arquivos locais.
• Use um agente externo do Claude no Duo Agent Platform para resolver o feedback de revisão de código diretamente na merge request - MR.

Pré-requisitos

1. Claude Code no terminal, configurado e em execução.
2. Um projeto GitLab com relatos de bugs e issues de proposta de recursos — por exemplo, o projeto Tanuki Iot Platform.
3. Para casos de uso específicos: o servidor MCP do GitLab e o GitLab Duo Agent Platform com agentes externos.
4. Para compilar o código: CMake, Make, gcc/clang++ para C++, Maven para Java.

Prepare o projeto GitLab

Se quiser acompanhar o tutorial, você pode repetir todas as etapas aqui no seu próprio ambiente de desenvolvimento. Para isso:

• Importe o projeto Tanuki Iot Platform para o seu ambiente GitLab, incluindo todos os issues abertos.
• Clone o projeto no seu ambiente local e navegue até ele.
• Abra um terminal e execute o Claude Code com claude.

      git clone https://gitlab.example.com/examplegroup/tanuki-iot-platform.git
cd tanuki-iot-platform

claude

    

Faça uma pergunta no prompt para saber mais sobre a finalidade do projeto.

      Sobre o que é este projeto?

    

Comece a usar o Claude Code com o GitLab

No nosso primeiro cenário, precisamos corrigir um sensor de hardware escrito em C++. O coletor Arduino lê métricas da placa Arduino Uno R4 conectada via USB e trava quando o dispositivo /dev/ttyACM0 não está conectado.

Issue do GitLab mostrando o relato de bug do travamento do coletor IoT Arduino

Depois de ler o relato de bug no Issue 4, inspecione o código no arquivo main.cpp, por exemplo, usando o vim:

      vim sensors/arduino-iot-collector/src/main.cpp

    

Código-fonte do Arduino IoT Collector aberto no vim

Compile e execute o binário do coletor com o CMake para reproduzir o problema.

      cmake -S . -B build
cmake --build build

./build/arduino_iot_collector
Starting Arduino IoT Collector Application...
libc++abi: terminating due to uncaught exception of type std::runtime_error: Failed to initialize Arduino temperature sensor: Arduino port not found: /dev/ttyACM0
[1]    85289 abort      ./build/arduino_iot_collector

    

Abra o Claude Code e insira o seguinte pedido:

      Pode me ajudar a corrigir o sensor do Arduino IoT Collector? Ele está travando.

    

O Claude Code pesquisa a base de código (codebase) e identifica o problema no arquivo main.cpp, que lança uma exceção std::runtime_error(), fazendo a aplicação travar imediatamente. O comportamento esperado é registrar um erro de configuração amigável ao usuário e continuar executando a aplicação normalmente.

Depois de corrigir e compilar o código com sucesso, precisamos criar uma branch do Git, um commit e uma merge request para disparar os pipelines de CI/CD, a verificação de segurança e os fluxos de revisão de código.

Você pode usar diferentes formas de trabalhar com o Git no Claude Code:

• Usar um prompt: Pode me ajudar a criar uma branch do Git, fazer o commit e enviar as alterações?
• Executar os comandos do shell: abra o prompt de comando com !, seguido dos comandos git checkout -b fix-arduino-sensor, git commit -avm "..." e git push. A saída do git push gera uma URL de criação da merge request. Clique nela para abrir o navegador e preencher o formulário.

Os pipelines de CI/CD são disparados na criação da MR e verificam se o build e os testes estão funcionando. A verificação de segurança garante que nenhuma vulnerabilidade nova seja introduzida. A nova MR dispara automaticamente o GitLab Duo Code Review Flow, que avalia a precisão da correção, de acordo com os guias de estilo de desenvolvimento e as instruções de revisão personalizadas.

Instruções personalizadas do GitLab Duo Code Review para C++

Comentário com feedback do GitLab Duo Code Review Flow

Veja abaixo uma gravação do Claude Code, do GitLab CI/CD e do GitLab Duo Agent Platform em ação:

Corrigindo um bug em C++ com o GitLab MCP no Claude Code

No cenário anterior, o Claude Code pesquisou o repositório de código local e fez suposições sobre uma possível correção com base no contexto disponível. No entanto, ele não tinha conhecimento do tíquete do GitLab que descrevia o bug, das discussões para a sua depuração e das soluções propostas para resolver o problema em definitivo. Além disso, ele também não levou em conta o histórico de alterações de código anteriores salvas em merge requests e issues com relatos parecidos, que são parte importante do contexto do ciclo de vida do desenvolvimento de software (SDLC).

Para permitir a utilização desse contexto rico do SDLC do GitLab, podemos integrar o servidor MCP do GitLab para o Claude Code.

Configure o servidor MCP do GitLab

Confirme que o servidor MCP do GitLab está habilitado na instância ou no grupo de nível superior.

Abra um novo terminal e adicione o servidor MCP do GitLab ao Claude Code usando o tipo de transporte http.

Substitua gitlab.example.com pela sua instância do GitLab ou use GitLab.com:

      claude mcp add --transport http GitLab https://gitlab.example.com/api/v4/mcp

    

Execute claude em uma nova sessão do terminal e digite /mcp para autenticar com o servidor MCP do GitLab, usando OAuth na página do navegador que será aberta.

      claude

/mcp

    

Para verificar a conexão, pergunte ao Claude:

      Quais ferramentas MCP do GitLab estão disponíveis para você?

Mostre a versão do servidor MCP do GitLab

    

Claude Code investigando a versão do servidor MCP do GitLab

Ao autenticar o Claude Code com o servidor MCP do GitLab, a conexão passa pelo OAuth e atua com a sua identidade já existente no GitLab e não com permissões elevadas ou separadas. Na prática, isso significa que o Claude Code só consegue ver projetos, issues (tíquetes), merge requests e outros dados do GitLab que você já tem acesso, seja pela sua conta ou seja pela sua participação em projetos e grupos. Essa é uma importante barreira de proteção: o MCP amplia o contexto dentro da ferramenta de IA, mas não contorna os controles de visibilidade do GitLab nem cria um acesso mais amplo por conta própria.

Uma segunda barreira de proteção é a aprovação do usuário. Nesse fluxo, o Claude Code identifica a ferramenta MCP que quer chamar e pede aprovação antes de seguir adiante, para que os desenvolvedores continuem no controle sempre que um contexto externo é buscado. Em ambientes sensíveis à segurança, também vale reforçar que os times devem ficar atentos aos dados expostos nos prompts e usar o MCP principalmente com conteúdo confiável do GitLab.

Trabalhe em um issue de relato de bug

Vamos buscar o contexto do tíquete no Claude Code referenciando o Issue 4 no prompt. Se você não tiver um tíquete no seu projeto, clone/copie o Issue 4 e ajuste o número no prompt.

      Pode me ajudar a corrigir o issue 4?

    

O Claude Code identifica a necessidade de chamar a ferramenta MCP get_issue e pede a sua aprovação, sendo que também é possível aprovar o uso futuro automaticamente.

Claude Code buscando o contexto do issue com ferramentas MCP

Depois que o Claude Code buscar o contexto necessário do issue, ele começa a analisar diretamente o código-fonte em C++ do sensor. Depois de criar e verificar uma correção, você pode pedir para criar uma nova branch do Git, um commit e uma MR, caso o Claude Code ainda não o faça automaticamente.

      Pode criar uma nova branch do Git, fazer o commit das alterações e criar uma nova merge request?

    

O Claude Code encontra a ferramenta MCP create_merge_request e cuida da criação da MR diretamente, sem precisar trocar de contexto para o navegador.

Claude Code criou uma MR usando ferramentas MCP, vinculada ao Issue 4

No GitLab, o evento de criação da MR dispara automaticamente vários fluxos de trabalho em paralelo:

• pipeline de CI/CD para builds e testes automatizados
• verificação de segurança com o Advanced SAST para C++
• um Code Review Flow pelo GitLab Duo Agent Platform

Esses fluxos de trabalho automatizados e agênticos dentro do GitLab aceleram a entrega de software tanto quanto o Claude Code acelera o desenvolvimento com IA para a resolução de issues.

Status do pipeline de CI/CD na MR - testes e verificação de segurança

Você pode abrir a Merge Request no navegador ou continuar no terminal e enviar o seguinte prompt ao Claude Code:

      A Merge Request está sendo executada corretamente?

    

Ele vai usar a ferramenta MCP get_merge_request_pipelines para buscar o status do pipeline da MR, confirmando que está verde e pronto para o merge.

Claude Code buscando o status do pipeline da MR usando ferramentas MCP

Veja a gravação para ver como o Claude Code resolve o problema com a ajuda do servidor MCP do GitLab:

Claude Code como agente externo revisor

Neste último cenário, o Claude Code ajudou a implementar um novo recurso com base nos requisitos do Issue 24 — um servidor de API Spring Boot com backend REST/Websocket. Os pipelines de CI/CD e as verificações de segurança estão OK, mas há feedback de revisão de código esperando na MR.

Feedback do GitLab Duo Code Review na MR do servidor de API Spring Boot

Você pode adicionar o Claude Code como parceiro de colaboração em issues, epics e MRs e resolver tarefas em conjunto. Siga a documentação de agentes externos para conhecer os pré-requisitos.

Ative o Claude Agent by GitLab no menu do projeto, em AI > Agents. Anote o nome da conta de serviço para saber como mencionar ou atribuir o agente depois — ele segue o padrão: @ai-<nome-do-agente>-<nome-do-grupo-de-nível-superior>.

Em seguida, abra a MR com o feedback de revisão de código e analise as alterações solicitadas. A captura de tela usa a MR 78, e o GitLab Duo Code Review segue as instruções de revisão personalizadas para Java.

Feedback do GitLab Duo Code Review Flow sobre AllowedOriginPatterns inseguro nos endpoints de API introduzidos na MR

Crie um novo comentário mencionando o Claude Code Agent:

      @ai-claude-agent-by-gitlab-<nome-do-grupo-de-nível-superior> Pode me ajudar a resolver o feedback da revisão?

    

Essa menção inicia uma nova sessão de agente em segundo plano, configurando o Claude Code Agent, que passa a trabalhar no feedback da revisão. Quando termina, ele segue as instruções para criar um commit no Git e um comentário com um resumo na MR.

Feedback do GitLab Duo Code Review resolvido pelo Claude Agent

Para garantir que o desenvolvimento de software permaneça dentro das diretrizes de proteção da sua organização, seus próximos passos incluem:

• Resolver o feedback de revisão restante.
• Revisar o aviso nos jobs do pipeline de CI/CD.
• Revisar as possíveis vulnerabilidades de segurança, usando, por exemplo, a Resolução de vulnerabilidades SAST.
• Obter a aprovação da merge request de um desenvolvedor elegível, configurado como Code Owner.

Widgets da merge request mostrando o pipeline de CI/CD, as aprovações exigidas, os achados de segurança e o status do merge

Assista a este vídeo para aprender como o Claude Code pode ajudar com revisões como agente externo no GitLab Duo Agent Platform:

Dicas para usar o Claude Code com o GitLab

Instruções personalizadas

É possível instruir os agentes a compilar e testar o código antes dos commits, manter as alterações mínimas ou entender melhor a arquitetura do projeto usando uma entrada no AGENTS.md. O Tanuki IoT Platform usa o seguinte exemplo de produção:

      ## Working with sensors

### Before editing
1. Identify the sensor directory you're working with
2. Check for an `AGENTS.md` file in that directory
3. Read sensor-specific instructions before making changes
4. Follow language-specific style guides

### Making changes
- Keep changes minimal and focused on the user request
- Do not refactor existing code unless specifically instructed
- Preserve original code formatting
- Only modify code necessary to solve the specific request

### Creating MRs
- Always run local builds and tests first
- Create a new branch for changes
- Automatically create a merge request after successful commits
- Reference relevant issues or tasks in the MR description

    

Essas instruções personalizadas também são processadas por agentes e flows no GitLab Duo Agent Platform.

O Claude Code prefere o CLAUDE.md, que também pode ser apontado para o AGENTS.md.

      @AGENTS.md

    

Resumo

As ferramentas de programação com IA tornam as equipes de desenvolvedores mais rápidas na hora de programar. Porém, escrever código e entregar software não são a mesma coisa, e essa diferença entre os dois cresce justamente porque as ferramentas são muito boas na primeira parte. Com elas, mais código é escrito, mas o backlog de bugs aumenta, as taxas de falha nos pipelines sobem e as vulnerabilidades de segurança se acumulam.

O Claude Code mantém a produtividade onde o código se localiza: entende bases de código desconhecidas, propõe correções e estrutura novos recursos rapidamente. O GitLab Duo Agent Platform é o que transforma essa velocidade — de muitos desenvolvedores em times de software de organizações empresariais — em software seguro que você realmente pode entregar e certificar em diversos marcos de release e projetos. Com o GitLab, o restante do ciclo de vida do software (como as correções no pipeline de CI/CD, a verificação de segurança, a remediação automatizada, revisão de código e muito mais, com fluxos de trabalho que mantêm humanos no controle) permite que cada ação dos agentes de IA seja rastreada e configurada para funcionar dentro das diretrizes de proteção e políticas de segurança da sua organização.

Neste tutorial, você viu três formas de unir o Claude Code e o GitLab Duo Agent Platform:

• Corrigir um bug com o Claude Code e deixar que o GitLab CI/CD, a verificação de segurança e o Duo Code Review façam o resto.
• Adicionar contexto do GitLab via MCP para que o Claude trabalhe a partir do contexto real salvo no issue do GitLab, e não apenas dos arquivos locais.
• Usar um agente externo com tecnologia Claude no GitLab Duo Agent Platform para resolver o feedback de revisão diretamente na MR.

O princípio se mantém o mesmo nos três casos: o Claude avança rápido, o GitLab certifica o trabalho.

Se você ainda não usa o GitLab Duo Agent Platform, pode começar com um teste gratuito da ferramenta.

Se você já usa o GitLab no plano gratuito, pode assinar o GitLab Duo Agent Platform seguindo alguns passos simples.

E se você já é assinante do GitLab Premium ou Ultimate, basta ativar o Duo Agent Platform e começar a usar os GitLab Credits incluídos na sua assinatura.