SonarQube: Code Quality Gates, Setup & CI Integration Guide

SonarQube is the industry-standard static analysis platform for tracking bugs, vulnerabilities, code smells, and test coverage across your codebase. This guide covers Docker setup, quality gate configuration, GitHub Actions integration, and how to read the reports that actually matter.

What Is SonarQube (vs ESLint and Semgrep)?

ESLint catches style and syntax issues within JavaScript files. Semgrep is a pattern-matching security scanner. SonarQube operates at a higher level: it tracks metrics over time, computes technical debt, measures test coverage, and enforces quality gates that block deployments. Unlike one-off linters, SonarQube maintains a persistent database of your project history so you can see whether quality is trending up or down.

Docker Quickstart

The fastest way to run SonarQube locally is with Docker Compose. This starts the server and a PostgreSQL database:

# docker-compose.yml
version: "3"
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - "9000:9000"
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar

# Start with:
docker compose up -d
# Open http://localhost:9000 — default login admin/admin

Connecting Your Project

After logging in, create a project and generate a token. Then run sonar-scanner from your project root:

npx sonar-scanner \
  -Dsonar.projectKey=my-project \
  -Dsonar.sources=src \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=YOUR_TOKEN \
  -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info

Quality Gates: Pass/Fail Criteria

A quality gate is a set of conditions your project must meet to pass. The built-in "Sonar Way" gate checks new code only — this is intentional: it lets you improve without being blocked by legacy debt. Common conditions to add:

• Coverage on new code >= 80%
• Duplicated lines on new code <= 3%
• Reliability Rating on new code = A (no new bugs)
• Security Rating on new code = A (no new vulnerabilities)
• Maintainability Rating on new code = A

GitHub Actions Integration

# .github/workflows/sonar.yml
name: SonarCloud Analysis
on: [push, pull_request]
jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history for blame data
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci && npm test -- --coverage
      - uses: SonarSource/sonarcloud-github-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          args: >
            -Dsonar.qualitygate.wait=true

Reading the Reports

The SonarQube dashboard splits issues into four categories:

SonarQube vs SonarCloud vs SonarLint

SonarLint is an IDE plugin (VS Code, IntelliJ) that gives real-time feedback as you type — it is the fastest feedback loop. SonarQube is self-hosted and used in CI pipelines. SonarCloud is the hosted SaaS version, free for public repos. In practice, teams run SonarLint locally for immediate feedback and SonarCloud/SonarQube in CI as a gate.