POTE/docs/17_sonarqube_setup.md

SonarQube Setup Guide for POTE

Complete guide for setting up SonarQube code quality analysis.

---

🎯 Overview

SonarQube provides:

• Code Quality Metrics - Maintainability, reliability, security
• Technical Debt - Time to fix issues
• Code Coverage - Test coverage visualization
• Code Smells - Code quality issues
• Security Vulnerabilities - Security hotspots
• Bug Detection - Potential bugs

---

📋 Prerequisites

1. SonarQube Server

• ✅ You mentioned you have the runner (SonarQube server)
• Server URL: http://your-sonarqube-server:9000 (or your URL)
• Server must be accessible from CI/CD runners

2. SonarQube Project

• Project key: pote (configured in sonar-project.properties)
• Project name: POTE
• Can be created manually or auto-created on first scan

3. SonarQube Token

• User token with permissions:
  • ✅ Execute Analysis (required)
  • ✅ Create Projects (if project doesn't exist)

---

🔧 Step 1: Create SonarQube Project

Option A: Create Manually (Recommended)

1. Login to SonarQube:

   http://your-sonarqube-server:9000
   

2. Create Project:

   • Go to: Projects → Create Project
   • Project Key: pote
   • Display Name: POTE
   • Main Branch: main
   • Click Set Up

3. Generate Token:

   • Go to: My Account → Security → Generate Token
   • Name: POTE CI/CD
   • Type: User Token
   • Expires: (set expiration or leave blank)
   • Click Generate
   • ⚠️ COPY THE TOKEN - You won't see it again!

Option B: Auto-Create (First Scan)

• Project will be created automatically on first scan
• Token must have "Create Projects" permission

---

🔐 Step 2: Configure Gitea Secrets

Add Secrets in Gitea

1. Go to Repository Settings:

   https://git.levkin.ca/ilia/POTE/settings/secrets/actions
   

2. Add Secret: SONAR_HOST_URL

   • Name: SONAR_HOST_URL
   • Value: http://your-sonarqube-server:9000
   • Example: http://10.0.30.169:9000
   • Click Add Secret

3. Add Secret: SONAR_TOKEN

   • Name: SONAR_TOKEN
   • Value: (paste the token from Step 1)
   • Click Add Secret

Verify Secrets

# In CI pipeline, secrets are available as:
${{ secrets.SONAR_HOST_URL }}
${{ secrets.SONAR_TOKEN }}

---

📄 Step 3: Project Configuration

File: sonar-project.properties

Already created in project root with these settings:

# Project identification
sonar.projectKey=pote
sonar.projectName=POTE
sonar.projectVersion=0.1.0

# Source code location
sonar.sources=src
sonar.sourceEncoding=UTF-8

# Test code location
sonar.tests=tests
sonar.test.inclusions=**/test_*.py

# Exclusions
sonar.exclusions=**/__pycache__/**,**/*.pyc,**/venv/**,**/tests/**,**/alembic/versions/**

# Python-specific settings
sonar.python.version=3.11

# Coverage reports
sonar.python.coverage.reportPaths=coverage.xml

Customize if Needed

Edit sonar-project.properties to:

• Change project key/name
• Add more exclusions
• Configure additional settings

---

🚀 Step 4: CI Pipeline Integration

Already Configured!

The CI pipeline (.github/workflows/ci.yml) includes:

1. SonarScanner Installation

   • Downloads and installs SonarScanner CLI
   • Version: 5.0.1.3006 (stable)

2. Coverage Report Generation

   • Runs pytest with coverage
   • Generates coverage.xml for SonarQube

3. SonarScanner Execution

   • Runs analysis
   • Uploads results to SonarQube server
   • Non-blocking (won't fail CI if SonarQube is unavailable)

Job: sonar-analysis

sonar-analysis:
  runs-on: ubuntu-latest
  env:
    SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
  steps:
    - Install SonarScanner
    - Generate coverage report
    - Run SonarScanner analysis

---

🧪 Step 5: Test Locally (Optional)

Install SonarScanner Locally

# Download SonarScanner
wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-5.0.1.3006-linux.zip
unzip sonar-scanner-cli-5.0.1.3006-linux.zip
export PATH=$PATH:$(pwd)/sonar-scanner-5.0.1.3006-linux/bin

Run Analysis Locally

cd /home/user/Documents/code/pote

# Generate coverage report
source venv/bin/activate
pytest tests/ --cov=src/pote --cov-report=xml

# Run SonarScanner
sonar-scanner \
  -Dsonar.host.url=http://your-sonarqube-server:9000 \
  -Dsonar.token=your_token_here

Or Use Environment Variables

export SONAR_HOST_URL=http://your-sonarqube-server:9000
export SONAR_TOKEN=your_token_here
sonar-scanner

---

📊 Step 6: View Results

In SonarQube UI

1. Go to Project:

   http://your-sonarqube-server:9000/dashboard?id=pote
   

2. View Metrics:

   • Overview - Overall quality gate status
   • Issues - Bugs, vulnerabilities, code smells
   • Measures - Coverage, complexity, duplications
   • Code - Source code with inline issues
   • Activity - Analysis history

Quality Gate

SonarQube will show:

• ✅ Pass - Meets quality standards
• ❌ Fail - Doesn't meet quality standards

Common Metrics

• Coverage - Test coverage percentage
• Duplications - Code duplication percentage
• Maintainability Rating - A-E rating
• Reliability Rating - A-E rating
• Security Rating - A-E rating
• Technical Debt - Time to fix all issues

---

🔧 Configuration Options

Quality Gate

Configure in SonarQube:

• Projects → POTE → Quality Gates
• Set thresholds for:
  • Coverage
  • Duplications
  • Bugs
  • Vulnerabilities
  • Code smells

Exclusions

Add to sonar-project.properties:

# Exclude specific files
sonar.exclusions=**/legacy/**,**/old_code/**

# Exclude specific issues
sonar.issue.ignore.multicriteria=e1
sonar.issue.ignore.multicriteria.e1.ruleKey=python:S1234
sonar.issue.ignore.multicriteria.e1.resourceKey=**/*.py

Coverage Exclusions

# Exclude from coverage
sonar.coverage.exclusions=**/tests/**,**/migrations/**,**/__init__.py

---

🐛 Troubleshooting

Issue: "Project 'pote' does not exist"

Solution:

1. Create project manually in SonarQube UI
2. OR ensure token has "Create Projects" permission

Issue: "Authentication failed"

Solution:

1. Verify SONAR_TOKEN secret is correct
2. Check token hasn't expired
3. Regenerate token if needed

Issue: "Connection refused"

Solution:

1. Verify SONAR_HOST_URL is correct
2. Check SonarQube server is running
3. Verify network connectivity from CI runner
4. Check firewall rules

Issue: "Coverage report not found"

Solution:

1. Ensure pytest runs before SonarScanner
2. Check coverage.xml is generated
3. Verify path in sonar-project.properties:

   sonar.python.coverage.reportPaths=coverage.xml
   

Issue: "No files to analyze"

Solution:

1. Check sonar.sources=src is correct
2. Verify source files aren't excluded
3. Check file encoding (should be UTF-8)

---

📈 Best Practices

1. Regular Analysis

• Run on every commit (already configured in CI)
• Review results regularly
• Fix issues incrementally

2. Quality Gate

• Set realistic thresholds
• Start with warnings, not failures
• Gradually increase standards

3. Coverage

• Aim for 80%+ coverage
• Focus on critical paths first
• Don't sacrifice quality for coverage

4. Technical Debt

• Track and reduce over time
• Prioritize high-impact issues
• Set time limits for fixing

5. Team Integration

• Share SonarQube dashboard with team
• Review issues in code reviews
• Use quality gate in PR checks

---

🔗 Integration with CI/CD

Current Setup

✅ Already Integrated:

• Runs automatically on every push
• Non-blocking (won't fail CI)
• Generates coverage report
• Uploads results to SonarQube

Make Quality Gate Blocking (Optional)

To fail CI if quality gate fails:

- name: Run SonarScanner
  run: |
    sonar-scanner \
      -Dsonar.qualitygate.wait=true \
      ...

Then remove continue-on-error: true from the step.

---

📝 Summary

Quick Setup Checklist

• SonarQube server running and accessible
• Project pote created in SonarQube (or auto-create enabled)
• Token generated with "Execute Analysis" permission
• SONAR_HOST_URL secret added to Gitea
• SONAR_TOKEN secret added to Gitea
• sonar-project.properties file exists (✅ already created)
• CI pipeline includes sonar-analysis job (✅ already added)
• Test by pushing to dev branch

Files Created

• ✅ sonar-project.properties - Project configuration
• ✅ .github/workflows/ci.yml - Updated with SonarScanner job

Next Steps

1. Add secrets to Gitea (Step 2)
2. Push to dev branch - CI will run SonarScanner
3. View results in SonarQube dashboard
4. Configure quality gate as needed
5. Review and fix issues incrementally

---

📞 Support

• SonarQube Docs: https://docs.sonarqube.org/
• SonarScanner Docs: https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/
• Python Plugin: https://docs.sonarqube.org/latest/analysis/languages/python/

---

Last Updated: December 2025
SonarScanner Version: 5.0.1.3006
Python Version: 3.11