Have you ever pushed code to a repository, only to have your CI/CD pipeline fail because of a SonarQube Quality Gate?

Understanding how SonarQube evaluates code does not just help pass automated checks—it makes it easier to catch reliability, security, and maintainability issues before an analysis even runs.

This guide breaks down SonarQube’s core architecture, how it calculates A–E ratings, what Technical Debt actually represents, and how to spot common flaws across JavaScript, React, and SQL.

1. The 4 Issue Categories: What Question to Ask?

SonarQube classifies code issues into four main categories. Each category answers a specific question about the code:

Category Core Question Example
Bug Could this cause the program to behave incorrectly or crash? Using assignment (=) instead of strict equality (===) inside an if condition.
Code Smell Does this make the code harder to read or maintain? Duplicated logic, overly long functions, or unused variables.
Vulnerability Can an attacker exploit this security weakness? Concatenating raw user input directly into an SQL query.
Security Hotspot Is this security-sensitive code that requires human review? Using dangerouslySetInnerHTML or innerHTML.

(Note: A single piece of code can trigger multiple rules at once.)

2. Real-World Examples Across JavaScript, React & SQL

JavaScript: Bug vs. Vulnerability

Bug (Assignment in Condition):

// Bug: Assigns 18 to age instead of comparing function checkAge(age) { if (age = 18) { return true; } return false; } // Fix: Use strict equality function checkAge(age) { if (age === 18) { return true; } return false; } // Vulnerability: Exploitable if email comes from untrusted input const sql = "SELECT * FROM users WHERE email = '" + email + "'"; db.query(sql); // Fix: Use parameterized queries db.query("SELECT * FROM users WHERE email = ?", [email]); // Bug: React will not re-render when mutating state directly function Counter() { const [count, setCount] = useState(0); function increment() { count = count + 1; } return <button onClick={increment}>{count}</button>; } // Fix: Use the state setter function setCount((prev) => prev + 1); // Bug: Displays stale user data if userId prop changes useEffect(() => { fetch("/api/users/" + userId) .then((res) => res.json()) .then((data) => setUser(data)); }, []); // Fix: Include userId in the dependency array useEffect(() => { fetch("/api/users/" + userId) .then((res) => res.json()) .then((data) => setUser(data)); }, [userId]); -- Design flaw: Allows duplicate IDs and duplicate emails CREATE TABLE employees ( id INT, email VARCHAR(255) ); -- Fix: Enforce data integrity with PRIMARY KEY and UNIQUE CREATE TABLE employees ( id INT PRIMARY KEY AUTO_INCREMENT, email VARCHAR(255) UNIQUE ); 
  1. How SonarQube Calculates Ratings (A to E) Reliability Rating (Bugs): Determined strictly by the highest-severity bug in the project.

A: 0 Bugs | B: ≥ 1 Minor | C: ≥ 1 Major | D: ≥ 1 Critical | E: ≥ 1 Blocker.

Example: Even with 10 Minor bugs, having a single Critical bug immediately drops the Reliability Rating to D.

Security Rating (Vulnerabilities): Follows the exact same worst-case severity scale (A to E) based on confirmed Vulnerabilities. (Security Hotspots do not directly lower this rating until reviewed and confirmed).

Maintainability Rating (Technical Debt Ratio): Based on Code Smells and the estimated time required to resolve them.

Technical Debt Ratio (TDR)
Technical Debt is the estimated time needed to fix all maintainability issues. SonarQube compares this to the estimated Development Cost (by default, 30 minutes per line of code):

TDR = (Technical Debt / Development Cost) × 100

A: ≤ 5%

B: 5% to < 10%

C: 10% to < 20%

D: 20% to < 50%

E: ≥ 50%

For example, a 4,000-line project has an estimated development cost of 2,000 hours (4,000 × 30 min). If SonarQube estimates 300 hours of technical debt, the TDR is 15% (300 / 2,000 × 100), resulting in a Maintainability Rating of C.

  1. Quality Gates: Why an "A" Project Can Still Fail A Quality Gate is a set of pass/fail conditions (PASSED or FAILED) enforced on code—typically focused on New Code—before merging or deploying to production.

Standard Quality Gate conditions include:

0 New Bugs and 0 New Vulnerabilities

100% of Security Hotspots reviewed

≥ 80% Test Coverage

≤ 3% Duplicated Lines

A Ratings across Reliability, Security, and Maintainability

Important Edge Case: A project can hold A, A, A ratings and still FAIL the Quality Gate. If test coverage drops below 80% or only 60% of Security Hotspots have been reviewed, the Quality Gate blocks the release even when zero bugs are detected.