Como usar o SonarQube para análise contínua de qualidade em pipelines

1. Conceitos fundamentais do SonarQube e análise estática

O SonarQube é uma plataforma de inspeção contínua de código-fonte que realiza análise estática automatizada para detectar bugs, vulnerabilidades de segurança, code smells, duplicação de código e medir cobertura de testes. Ele se integra a pipelines CI/CD para garantir que a qualidade do código seja verificada a cada commit, antes da mesclagem ou deploy.

As principais métricas do SonarQube incluem:

  • Bugs: problemas que podem levar a falhas em tempo de execução
  • Vulnerabilidades: brechas de segurança no código
  • Code Smells: más práticas de programação que prejudicam manutenibilidade
  • Duplicação: blocos de código repetidos que aumentam dívida técnica
  • Cobertura de testes: percentual de código exercitado por testes unitários

Quality Gates são conjuntos de condições que definem se um projeto atende aos padrões de qualidade aceitáveis. Por exemplo, um Quality Gate pode exigir cobertura mínima de 80% e zero vulnerabilidades críticas. Quality Profiles são conjuntos de regras de análise aplicadas a uma linguagem específica, podendo ser customizados por equipe.

2. Preparação do ambiente: instalação e configuração inicial

A instalação do SonarQube Server pode ser feita via Docker para ambientes locais ou usando o SonarCloud (versão SaaS) para projetos hospedados na nuvem.

Exemplo de execução do SonarQube com Docker:

docker run -d --name sonarqube \
  -p 9000:9000 \
  -e SONAR_JDBC_URL=jdbc:postgresql://localhost:5432/sonarqube \
  -e SONAR_JDBC_USERNAME=sonar \
  -e SONAR_JDBC_PASSWORD=sonar \
  sonarqube:lts-community

Após a instalação, acesse http://localhost:9000 com credenciais padrão (admin/admin). Crie um projeto manualmente ou via API REST, e gere um token de autenticação em My Account > Security > Generate Tokens.

Para integrar com repositórios, configure webhooks no GitHub/GitLab para notificar o SonarQube sobre novos commits e pull requests. Isso permite análise automática de branches e PRs.

3. Configuração do SonarScanner em pipelines CI/CD

O SonarScanner é a ferramenta CLI que executa a análise do código e envia os resultados ao servidor SonarQube. Em pipelines, ele deve ser instalado e configurado com parâmetros essenciais.

Parâmetros obrigatórios:

sonar.projectKey=meu-projeto
sonar.sources=src
sonar.host.url=http://localhost:9000
sonar.login=SEU_TOKEN
sonar.language=java

Exemplo de configuração para pipeline no GitHub Actions:

name: SonarQube Analysis
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@v2
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

Para GitLab CI, o bloco equivalente seria:

sonarqube-check:
  image: sonarsource/sonar-scanner-cli:latest
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
  script:
    - sonar-scanner
      -Dsonar.projectKey=meu-projeto
      -Dsonar.sources=src
      -Dsonar.host.url=$SONAR_HOST_URL
      -Dsonar.login=$SONAR_TOKEN
  only:
    - merge_requests
    - main

4. Análise incremental e branch analysis

Para otimizar o tempo de execução em pipelines, o SonarQube suporta análise incremental, que processa apenas arquivos modificados desde a última análise bem-sucedida. Isso é ativado automaticamente quando a análise é executada no mesmo branch.

Para análise de branches de feature:

sonar-scanner \
  -Dsonar.projectKey=meu-projeto \
  -Dsonar.branch.name=feature/nova-funcionalidade \
  -Dsonar.sources=src

Para análise de pull requests, utilize os parâmetros específicos:

sonar-scanner \
  -Dsonar.projectKey=meu-projeto \
  -Dsonar.pullrequest.key=123 \
  -Dsonar.pullrequest.branch=feature/nova-funcionalidade \
  -Dsonar.pullrequest.base=main

No GitHub Actions, o SonarScanner detecta automaticamente o contexto do PR se fetch-depth: 0 estiver configurado. No GitLab CI, use only: merge_requests para acionar a análise apenas em MRs.

5. Quality Gates como gatekeeper do pipeline

Quality Gates são o mecanismo principal para bloquear deploys ou merges quando a qualidade do código não atende aos critérios definidos. No SonarQube, vá até Quality Gates e crie um novo gate com condições como:

  • Cobertura de código < 80% → FAIL
  • Bugs críticos > 0 → FAIL
  • Vulnerabilidades > 0 → FAIL
  • Duplicação > 3% → FAIL

Para integrar o Quality Gate no pipeline, verifique o status via API REST após a análise:

# Script para verificar Quality Gate
SONAR_TOKEN="seu_token"
PROJECT_KEY="meu-projeto"
ANALYSIS_ID=$(curl -s -u $SONAR_TOKEN: \
  "http://localhost:9000/api/ce/activity?component=$PROJECT_KEY&status=SUCCESS" \
  | jq -r '.tasks[0].analysisId')

QUALITY_GATE_STATUS=$(curl -s -u $SONAR_TOKEN: \
  "http://localhost:9000/api/qualitygates/project_status?analysisId=$ANALYSIS_ID" \
  | jq -r '.projectStatus.status')

if [ "$QUALITY_GATE_STATUS" != "OK" ]; then
  echo "Quality Gate FAILED: $QUALITY_GATE_STATUS"
  exit 1
else
  echo "Quality Gate PASSED"
fi

Esse script pode ser adicionado como etapa final do pipeline, interrompendo a execução se o Quality Gate falhar. Em GitHub Actions, use continue-on-error: false para garantir o bloqueio.

6. Geração e publicação de relatórios de qualidade

O SonarQube fornece dashboards detalhados com gráficos de evolução de métricas ao longo do tempo, distribuição de code smells por severidade e histórico de Quality Gate. Esses relatórios são acessíveis diretamente na interface web do servidor.

Para publicar badges de qualidade no README do repositório, utilize o endpoint de badges do SonarQube:

[![Quality Gate Status](http://localhost:9000/api/project_badges/measure?project=meu-projeto&metric=alert_status)](http://localhost:9000/dashboard?id=meu-projeto)
[![Coverage](http://localhost:9000/api/project_badges/measure?project=meu-projeto&metric=coverage)](http://localhost:9000/dashboard?id=meu-projeto)

Notificações automáticas podem ser configuradas via webhooks no SonarQube para enviar alertas ao Slack, e-mail ou Microsoft Teams sempre que um Quality Gate falhar ou métricas degradarem significativamente.

7. Boas práticas e manutenção contínua

Para manter a eficácia da análise contínua, adote as seguintes práticas:

  1. Revisão periódica de Quality Profiles: atualize regras conforme novas versões do SonarQube e evolução das linguagens. Remova regras obsoletas e adicione novas para tecnologias emergentes.

  2. Tratamento de falsos positivos: use anotações NOSONAR para suprimir alertas incorretos, mas sempre com justificativa documentada no código:
    text // NOSONAR: regra S1234 é falso positivo neste contexto devido à biblioteca externa

  3. Estratégias para dívida técnica: para projetos legados, defina Quality Gates progressivos. Comece com tolerância maior e reduza gradualmente a cada sprint. Use a métrica "Dívida Técnica" para priorizar refatorações.

  4. Análise em paralelo: divida projetos grandes em módulos menores, cada um com seu próprio Quality Gate, para reduzir tempo de análise e isolar problemas.

  5. Manutenção do servidor: agende limpeza periódica de dados antigos (via sonar.ce.cleanup.period) para evitar degradação de performance.

Referências