Skip to main content

SonarQube Code Quality Analysis Configuration Guide

This document describes how to configure and use SonarQube for code quality analysis.

Overview​

SonarQube is an open-source code quality management platform used to continuously detect code quality, security, and reliability. The iForge project has been configured with SonarQube integration to support automated code analysis.

Features​

  • Code Quality Checks: Detects code smells, duplicate code, and complexity issues
  • Security Vulnerability Scanning: Identifies common security vulnerabilities (SQL injection, XSS, command injection, etc.)
  • Test Coverage: Integrates Go and TypeScript test coverage reports
  • Technical Debt Tracking: Quantifies technical debt and provides fix recommendations
  • Quality Gates: Sets quality thresholds to prevent low-quality code from being merged

Local Deployment of SonarQube​

Prerequisites​

  • Docker and Docker Compose
  • At least 4GB of available memory
  • At least 10GB of disk space

Starting SonarQube​

# Enter the project root directory
cd d:\code\iforge\iforge

# Start SonarQube and PostgreSQL
docker-compose -f deploy/sonarqube/docker-compose.yml up -d

# View logs
docker-compose -f deploy/sonarqube/docker-compose.yml logs -f sonarqube

Accessing SonarQube​

You will need to change the password after the first login.

Stopping SonarQube​

docker-compose -f deploy/sonarqube/docker-compose.yml down

Cleaning Data (Optional)​

docker-compose -f deploy/sonarqube/docker-compose.yml down -v

Configuring GitHub Actions​

1. Get SonarQube Token​

  1. Login to SonarQube: http://localhost:9000
  2. Go to My Account → Security
  3. In the Generate Tokens section, create a new token
  4. Name the token (e.g., github-actions), select type Global Analysis
  5. Copy the generated token

2. Configure GitHub Secrets​

Configure the following secrets in the GitHub repository:

  1. Go to repository Settings → Secrets and variables → Actions
  2. Add the following secrets:
    • SONAR_TOKEN: The token generated in the previous step
    • SONAR_HOST_URL: SonarQube server URL
      • Local testing: http://host.docker.internal:9000 (Docker Desktop)
      • Production: https://sonarqube.your-domain.com

3. Trigger Analysis​

After configuration, the following events will automatically trigger SonarQube analysis:

  • Push to main branch
  • Pull Request to main branch

Running Analysis Locally​

Install SonarScanner​

# Download SonarScanner
# Windows
choco install sonarscanner

# macOS
brew install sonar-scanner

# Or manually download: https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/

Run Analysis​

# Enter the project root directory
cd d:\code\iforge\iforge

# Generate Go test coverage
cd server
go test ./... -coverprofile=coverage.out -covermode=atomic
cd ..

# Run SonarScanner
sonar-scanner \
  -Dsonar.projectKey=iforge \
  -Dsonar.sources=server,web \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=YOUR_TOKEN

Configuration File Description​

sonar-project.properties​

The sonar-project.properties file in the project root directory contains SonarQube analysis configuration:

# Project identifier
sonar.projectKey=iforge
sonar.projectName=iForge
sonar.projectVersion=1.0.0

# Source code location
sonar.sources=server,web

# Test coverage report paths
sonar.go.coverage.reportPaths=server/coverage.out
sonar.javascript.lcov.reportPaths=web/coverage/lcov.info

# Exclusion rules
sonar.exclusions=**/node_modules/**,**/vendor/**,**/*.pb.go

CI Workflow Configuration​

.github/workflows/ci.yml contains SonarQube analysis steps:

sonarqube:
  name: SonarQube Analysis
  runs-on: ubuntu-latest
  needs: [backend, frontend]
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    
    - name: SonarQube Scan
      uses: SonarSource/sonarqube-scan-action@v4
      env:
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

Quality Gate Configuration​

Built-in Quality Gates​

SonarQube provides default quality gates with the following conditions:

  • Coverage: New code coverage ≥ 80%
  • Duplication: New code duplication rate ≤ 3%
  • Maintainability: No new Code Smells
  • Reliability: No new Bugs
  • Security: No new Vulnerabilities

Custom Quality Gates​

  1. Go to Quality Gates → Create
  2. Add conditions, for example:
    • Coverage on New Code ≥ 70%
    • Duplicated Lines (%) on New Code ≤ 5%
    • Maintainability Rating on New Code = A
  3. Apply the quality gate to the project

Common Issues​

Q: SonarQube fails to start​

A: Check the following:

  • Ensure Docker has sufficient memory (at least 4GB)
  • Check if port 9000 is occupied
  • View logs: docker-compose logs sonarqube

Q: Analysis fails with "coverage report not found"​

A: Make sure to run tests first to generate the coverage report:

cd server && go test ./... -coverprofile=coverage.out

Q: Quality Gate check fails​

A: Check the SonarQube dashboard to analyze specific issues:

  • Insufficient coverage: Add more unit tests
  • Duplicate code: Refactor duplicate logic
  • Code smells: Fix issues flagged by SonarQube

Q: How to exclude certain files​

A: Configure in sonar-project.properties:

sonar.exclusions=**/generated/**,**/vendor/**

Best Practices​

  1. Regular Review: Review SonarQube reports weekly and address new issues promptly
  2. Progressive Improvement: Focus on new code quality first, gradually clean up technical debt
  3. Team Collaboration: Include SonarQube reports in the code review process
  4. Automation: Configure CI/CD for automatic analysis to prevent low-quality code from being merged
  5. Continuous Learning: Refer to SonarQube's fix recommendations to improve team coding skills