SonarQube 사용법 완전 정리

코드 품질을 수치로 관리하는 방법

코드를 잘 짠다는 것은 감각의 문제가 아니라 지표의 문제다.
SonarQube는 코드 품질을 정량화하고, 팀 단위로 관리할 수 있게 해주는 정적 분석 플랫폼이다.

이 글에서는 SonarQube의 개념부터 설치, Spring Boot 프로젝트 연동, 그리고 CI/CD 품질 게이트 설정까지 정리한다.

---

1. SonarQube란 무엇인가?

SonarQube는 코드 분석 도구다.

다음 항목을 자동으로 분석한다.

• Bug
• Vulnerability
• Code Smell
• 중복 코드
• 복잡도 (Cyclomatic Complexity)
• 테스트 커버리지
• Maintainability Rating
• Security Hotspot

즉, “코드 리뷰 자동화 플랫폼”이라고 보면 된다.

 

 

2. SonarQube vs SonarCloud 차이

구분                                                                                SonarQube                                                  SonarCloud

 

설치 방식	직접 서버 구축	SaaS
유지보수	필요	불필요
개인 프로젝트	번거로움	추천
기업 내부망	적합	제한적

개인 GitHub 프로젝트라면 SonarCloud가 더 간편하다.

---

3. SonarQube 설치 (Docker 기준)

docker run -d \

--name sonarqube \
-p 9000:9000 \
sonarqube:lts

 

접속:

http://localhost:9000

 

기본 계정:

id: admin
pw: admin

 

---

4. Spring Boot 프로젝트 연동 (Gradle Kotlin DSL)

1️⃣ plugin 추가

plugins {
id("org.sonarqube") version "4.4.1.3373"
}

 

---

2️⃣ sonar 설정

sonarqube {
properties {
property("sonar.projectKey", "lemuel-settlement")
property("sonar.host.url", "http://localhost:9000")
property("sonar.login", System.getenv("SONAR_TOKEN"))
}
}

 

---

3️⃣ 토큰 발급

SonarQube → My Account → Security → Generate Token

그리고 환경변수 설정:

 

 

export SONAR_TOKEN=발급받은_토큰

 

---

4️⃣ 분석 실행

 

 

./gradlew sonar

 

분석이 완료되면 대시보드에서 결과를 확인할 수 있다.

---

5. 테스트 커버리지 연동 (JaCoCo)

 

 

plugins {
jacoco
}

tasks.test {
finalizedBy(tasks.jacocoTestReport)
}

tasks.jacocoTestReport {
reports {
xml.required.set(true)
}
}

 

Sonar는 JaCoCo XML 리포트를 읽어 커버리지를 계산한다.

---

6. GitHub Actions CI 연동

 

 

name: CI

on:
pull_request:
push:
branches: [ main ]

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Set up JDK
uses: actions/setup-java@v4
with:
distribution: 'temurin'
java-version: '17'

- name: Build and Test
run: ./gradlew clean build

- name: SonarQube Scan
run: ./gradlew sonar
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

 

GitHub → Settings → Secrets → SONAR_TOKEN 등록 필요.

---

7. Quality Gate 설정

Quality Gate는 “코드가 일정 기준 이상이어야 통과”하도록 만드는 장치다.

예시 기준:

• Coverage ≥ 70%
• New Code에 Bug 0개
• Security Rating A
• Maintainability Rating A

PR에서 Quality Gate가 실패하면 Merge를 막을 수 있다.

이게 SonarQube의 핵심 가치다.

---

8. 실무에서 SonarQube를 쓰는 이유

1. 코드 품질을 수치화
2. 리뷰 비용 절감
3. 리팩토링 기준 명확화
4. 신규 코드 품질 관리 가능
5. 기술 부채 추적 가능

특히 헥사고날 아키텍처처럼 레이어 분리가 중요한 프로젝트에서는
아키텍처 침범 여부를 감지하는 보조 수단으로도 유용하다.

---

9. 단점

• 초기 세팅이 번거롭다
• false positive가 존재한다
• 커스터마이징 없이 쓰면 소음이 많다

따라서 팀 기준에 맞게 Quality Profile을 조정하는 것이 중요하다.

---

10. 결론

SonarQube는 단순한 정적 분석 도구가 아니다.
코드 품질을 “감”이 아닌 “지표”로 관리하는 플랫폼이다.

특히 다음과 같은 경우 필수에 가깝다.

• 팀 단위 개발
• 장기 유지보수 프로젝트
• SI 이후 운영 유지 프로젝트
• 포트폴리오 품질 관리

개인 프로젝트라도 SonarCloud를 붙여두면
코드 신뢰도는 확실히 올라간다.