Quality Gate: Verificações locais e na CI sem depender de SonarCloud
Publicado originalmente no LinkedIn em 10/10/2026.
Fazia tempo que eu sentia falta de um quality gate que pudesse rodar localmente no meu terminal e na esteira de CI sem depender de subir o código para o SonarQube ou SonarCloud apenas para descobrir se algo quebrou ou se a cobertura caiu.
A ideia nasceu após acompanhar reflexões do Lucas Montano sobre governança e qualidade de software: peguei os conceitos essenciais e adaptei para o meu fluxo diário de desenvolvimento, concentrando tudo em uma CLI rápida e determinística chamada quality-gate.
Por que validar localmente antes da nuvem?
Esperar o feedback da esteira remota consome minutos preciosos e polui o histórico do GitHub com commits de correção trivial (fix: lint, fix: types). Rodar as mesmas regras no terminal antes do commit elimina idas e vindas desnecessárias:
# Executa o gate completo no repositório atual
npx quality-gate check --ratchet
O objetivo principal é transformar a qualidade em um contrato reproduzível: o que passa na máquina do desenvolvedor passa rigorosamente na CI.
Verificações concentradas no pipeline
O gate unifica verificações que tradicionalmente ficam espalhadas em scripts e ferramentas distintas:
- Linting & Code Smells: Integração direta com ESLint e regras do SonarJS para detectar complexidade ciclomática e vulnerabilidades estáticas;
- Bateria de Testes: Execução paralela dos testes unitários e de integração;
- Ratchet de Cobertura: Travamento automático contra regressão de testes;
- Auditoria de Dependências: Varredura de CVEs e licenças proibidas em ecossistemas Node.js e Python (
uv); - Secret Scan Determinístico: Detecção de credenciais, chaves privadas e tokens vazados;
- Docker Image Gate: Validação estática de Dockerfile e camadas de build;
- Relatório de Pull Request: Geração de sumário formatado em Markdown pronto para o GitHub Actions.
Como funciona o Ratchet de Cobertura
Definir uma meta estática (como "mínimo de 80%") tem uma falha grave: se a cobertura de um módulo estiver em 95%, alguém pode adicionar 100 linhas sem teste e derrubar para 81% sem que a esteira reclame.
O mecanismo de ratchet resolve isso registrando o índice atual como piso obrigatório:
{
"ratchet": {
"lines": 94.2,
"statements": 93.8,
"functions": 95.0,
"branches": 91.5
}
}
Se a cobertura subir em um PR, o novo valor passa a ser o patamar mínimo permanente. Se cair mesmo 0.1%, o gate rejeita o merge.
Execução efêmera para qualquer repositório
Um dos requisitos que eu mais queria era auditar repositórios sem precisar instalar pacotes globais ou criar arquivos de lock permanentes dentro do projeto:
# Audita repositório alvo em modo efêmero sem alterar arquivos locais
npx quality-gate audit --dir /caminho/do/projeto --strict
O gate inspeciona o estado do Pull Request (conflitos pendentes, checks obrigatórios da branch e threads de review não resolvidas) antes de sinalizar aprovação.
Detalhe para quem clonar o repositório e rodar os testes: existem chaves e tokens propositalmente falsos na suite de testes para validar se o scanner de segredos realmente os intercepta.
Código open source disponível no GitHub.
Mídia da publicação
