sonarqube-rules
Overview
Per github.com/SonarSource/sonarqube:
"SonarQube provides the capability to not only show the health
of an application but also to highlight issues newly introduced."
The platform's distinguishing features vs Semgrep / CodeQL:
- Quality Gate - pass/fail decision based on configurable
threshold conditions (coverage on new code, duplication, security
hotspots reviewed, maintainability rating, etc.).
- New-code-period - issues are categorized as "new code" vs
"overall code"; gates focus on new-code metrics so legacy debt
doesn't block deploys.
- Persistent issue tracking - server-side storage of issues
across scans; status workflow (open / confirmed / resolved / false
positive / won't fix).
- Cross-language coverage - 30+ languages with one tool +
unified UI.
When to use
- Existing SonarQube deployment (Community / Developer / Enterprise
/ SonarCloud).
- The team needs persistent issue tracking + Quality Gate workflow.
- Multi-language coverage in one platform is a requirement.
- New-code-period gating fits the team's deploy cadence.
For new projects without a SonarQube investment, evaluate
semgrep-rules (lower friction; no
server) first.
Step 1 - Install (server side)
Per docs.sonarsource.com/sonarqube-server:
Docker (most common for evaluation):
docker run -d --name sonarqube \
-p 9000:9000 \
sonarqube:lts-community
For production, consult sq-docs for Postgres + JVM
sizing + reverse-proxy configuration. Default admin: admin /
admin (change immediately).
Step 2 - sonar-scanner CLI
Download from docs.sonarsource.com/sonarqube-server →
"Analysis scanners". Place on PATH.
sonar-scanner \
-Dsonar.projectKey=my-project \
-Dsonar.sources=. \
-Dsonar.host.url=http://localhost:9000 \
-Dsonar.token=$SONAR_TOKEN
For Maven / Gradle / .NET, use the language-native scanner plugin
(mvn sonar:sonar / ./gradlew sonar / dotnet sonarscanner).
Step 3 - sonar-project.properties config
Project-root file replaces -D flags:
# sonar-project.properties
sonar.projectKey=my-project
sonar.projectName=My Project
sonar.sources=src
sonar.tests=tests
sonar.exclusions=**/*.spec.ts,**/generated/**
sonar.sourceEncoding=UTF-8
# Coverage from external tool (Jest, JaCoCo, etc.)
sonar.javascript.lcov.reportPaths=coverage/lcov.info
# New-code-period (analysis scope)
sonar.newCode.referenceBranch=main
# Quality Gate (referenced by ID; created via UI/API)
sonar.qualitygate.wait=true
sonar.qualitygate.wait=true makes the scanner block until the
gate decision is computed - critical for CI gating.
Step 4 - Quality Gate concept
The default "Sonar Way" gate enforces (consult your SonarQube UI
at Quality Gates → Sonar Way for current conditions):
- Coverage on New Code ≥ X%
- Duplicated Lines on New Code ≤ Y%
- Maintainability Rating on New Code = A
- Reliability Rating on New Code = A
- Security Rating on New Code = A
- Security Hotspots on New Code reviewed = 100%
Custom gates can be defined via UI or REST API
(/api/qualitygates/create).
Step 5 - Branch + PR analysis
For PR analysis (Developer edition+):
sonar-scanner \
-Dsonar.pullrequest.key=$PR_NUMBER \
-Dsonar.pullrequest.branch=$PR_BRANCH \
-Dsonar.pullrequest.base=main
PR results post as comments to GitHub / GitLab / Bitbucket per
the integration setup in SonarQube admin.
Step 6 - False-positive triage (MANDATORY)
Three suppression layers in priority order:
| Mechanism | Example | When to use |
|---|
Per-line NOSONAR | int x = 0; // NOSONAR justification text | Single-line exception with inline reason |
| Annotation | @SuppressWarnings("squid:S106") | Java/Kotlin per-block exception |
| Server-side mark-as-FP | UI: Issues → Resolve as False Positive | Persistent across scans; auditable |
| Server-side mark-as-Won't Fix | UI: Issues → Resolve as Won't Fix | Acknowledged risk; not a defect |
Justification template (mandatory in code):
// NOSONAR squid:S106 - Reason: required for CLI tool stdout output
// Reviewer: alice@example.com (2026-05-15)
// Expires: 2026-12-15
System.out.println(message);
Server-side resolution requires a comment per SonarQube workflow
config - make it mandatory in admin settings (Administration → Configuration → Issues → Comment required to set status).
Cadence: Issues → False Positive filter periodically; review for
expiration. Server-side resolutions are persistent and auditable -
the audit trail is the value over Semgrep's per-comment approach.
Step 7 - CI integration
jobs:
sonarqube:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with: { fetch-depth: 0 } # full history needed for new-code-period
- uses: SonarSource/sonarqube-scan-action@v5
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
- uses: SonarSource/sonarqube-quality-gate-action@v1
timeout-minutes: 5
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
fetch-depth: 0 is critical - without full git history, new-code-period
detection is broken.
Step 8 - REST API integration
For automation / dashboards:
| Endpoint | Use |
|---|
GET /api/issues/search?projectKeys=... | Issue list with filters |
GET /api/qualitygates/project_status | Current gate verdict |
POST /api/issues/do_transition | Mark FP / Won't Fix |
GET /api/measures/component_tree | Per-file metrics |
API token via User → My Account → Security → Generate Tokens.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
fetch-depth: 1 in CI | New-code-period broken; gates produce wrong decisions | Always fetch-depth: 0 (Step 7) |
Skip sonar.qualitygate.wait | CI exits before gate evaluates; missed regressions | sonar.qualitygate.wait=true (Step 3) |
| NOSONAR without justification | Server-side audit trail empty | Required template (Step 6) |
| Custom Quality Gate without team buy-in | Gate fails on PRs no one understands | Document gate definition; reference in PR template |
| Mass-resolve as FP without review | Backdoor for skipping security findings | Require comment + reviewer attribution (Step 6) |
Limitations
- SonarQube server requires hosting + maintenance; SonarCloud is
the SaaS alternative.
- Branch + PR analysis are Developer-edition+ features - Community
edition only supports main branch.
- Some language-specific deep-rule features require Developer or
Enterprise edition.
- New-code-period requires accurate git history; shallow clones
break it.
- License changed from LGPL to SSPL in 2024 - verify license
compatibility for commercial use.
References
- sq-gh - repository
- sq-docs - official SonarQube documentation root
- docs.sonarsource.com/sonarqube-server/latest/user-guide/quality-gates - Quality Gates user guide
- docs.sonarsource.com/sonarqube-server/latest/user-guide/issues - Issue workflow + transitions
semgrep-rules,
codeql-queries,
language-native-sast - sister scanners