SonarQube

작성자

익명

작성일

2026.08.13

조회수

버전

SonarQube 정적 코드 분석 코드 품질 관리 기술 부채 품질 게이트 Docker CI/CD GitHub Actions 소프트웨어 보안 중급

SonarQube

1. 개요

SonarQube는 소스 코드의 품질과 보안을 자동으로 검사하여 코드의 결함을 찾아내고 관리하는 오픈 소스 기반의 정적 코드 분석(Static Code Analysis) 플랫폼이다.

정적 코드 분석이란 프로그램을 실제로 실행하지 않고 소스 코드 자체를 분석하여 잠재적인 버그, 보안 취약점, 코딩 표준 위반 사례를 찾아내는 기법을 의미한다. SonarQube는 소프트웨어 개발 생명주기(SDLC, Software Development Life Cycle) 전반에 걸쳐 코드 리뷰 과정을 자동화함으로써, 개발 초기 단계에서 결함을 발견하고 수정하게 하여 최종 제품의 안정성을 높이는 역할을 수행한다.

2. 주요 분석 지표

SonarQube는 코드의 상태를 정량적으로 측정하기 위해 다음과 같은 핵심 지표를 사용한다.

2.1 핵심 지표 정의

버그(Bugs): 코드 실행 시 잘못된 동작을 유발하거나 런타임 오류를 일으킬 가능성이 높은 결함이다.
취약점(Vulnerabilities): 해커가 악용할 수 있는 보안상의 허점으로, SQL 인젝션이나 크로스 사이트 스크립팅(XSS) 등이 이에 해당한다.
코드 스멜(Code Smells): 기능적으로는 동작하지만, 유지보수를 어렵게 만드는 설계상의 문제나 가독성이 떨어지는 코드 패턴을 의미한다.
기술 부채(Technical Debt): 당장의 빠른 구현을 위해 선택한 임시방편적인 코드나 낮은 품질의 코드를 수정하는 데 필요한 예상 시간과 비용을 의미한다.

2.2 지표별 비교

지표	정의	위험도	영향 범위	해결 우선순위
버그	논리적 오류 및 런타임 결함	높음	애플리케이션 기능 마비	최상
취약점	보안상 허점 및 공격 경로	매우 높음	데이터 유출 및 시스템 침해	최상
코드 스멜	유지보수성 저해 요소	낮음	개발 생산성 및 가독성 저하	보통

3. 작동 원리 및 아키텍처

SonarQube는 분산된 구조를 통해 코드 스캔부터 결과 리포팅까지의 과정을 처리한다.

3.1 워크플로우

스캔(Scan): <a href="/doc/%EA%B8%B0%EC%88%A0/%EC%86%8C%ED%94%84%ED%8A%B8%EC%9B%A8%EC%96%B4/%EB%B6%84%EC%84%9D%20%EB%8F%84%EA%B5%AC/SonarScanner" class="wiki-link wiki-link-missing">SonarScanner</a>가 프로젝트 소스 코드를 읽어 분석 데이터를 생성한다.
전송(Send): 생성된 분석 리포트를 HTTP 통신을 통해 SonarQube Server로 전송한다.
처리(Process): 서버 내의 Compute Engine이 큐(Queue)에서 분석 리포트를 가져와 실제 분석을 수행하고, 설정된 규칙(Quality Profile)에 따라 위반 사항을 판별하여 이슈를 생성한다.
저장 및 표시(Store & Display): 분석 결과는 Database에 저장되며, 사용자는 웹 UI를 통해 대시보드 형태로 결과를 확인한다.

3.2 아키텍처 구성 요소

SonarScanner: 각 언어별(Java, JS, Python 등) 스캐너가 설치된 환경에서 코드를 분석하는 클라이언트 도구이다.
SonarQube Server: 분석 엔진(Compute Engine), 웹 인터페이스, API 서버를 포함하는 중앙 제어 시스템이다.
Database: 프로젝트 설정, 분석 이력, 이슈 상태 등을 저장하는 영속성 계층(PostgreSQL, Oracle, Microsoft SQL Server 등 지원)이다.

4. 핵심 기능 및 활용

4.1 품질 게이트 (Quality Gates)

품질 게이트는 프로젝트가 다음 단계(예: 배포)로 넘어가기 위해 충족해야 하는 최소한의 품질 기준이다. 예를 들어 "새로운 코드의 버그가 0개여야 함", "테스트 커버리지가 80% 이상이어야 함"과 같은 조건을 설정하여, 기준 미달 시 빌드를 실패(Fail) 처리함으로써 품질 저하를 원천 차단한다.

4.2 품질 프로필 (Quality Profiles)

품질 프로필은 분석 시 적용할 코딩 규칙의 집합이다. 언어별로 기본 제공되는 규칙 세트가 있으며, 조직의 코딩 컨벤션에 맞게 특정 규칙을 활성화하거나 비활성화하여 커스텀 프로필을 생성할 수 있다.

4.3 다국어 지원

SonarQube는 Java, C#, JavaScript, TypeScript, Python, Go, Kotlin, Swift 등 25개 이상의 주요 프로그래밍 언어를 지원하여 폴리글랏(Polyglot) 환경에서도 통합 관리가 가능하다.

5. 설치 및 초기 설정 가이드

SonarQube는 DB 분리가 필수적이므로 Docker Compose를 이용한 설치가 가장 권장된다.

5.1 Docker Compose를 이용한 설치

먼저 docker-compose.yml 파일을 다음과 같이 작성한다.

version: '3'
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - "9000:9000"
    networks:
      - sonarnet
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonar
      - SONAR_JDBC_USERNAME=sonar
      - SONAR_JDBC_PASSWORD=sonar
    depends_on:
      - db

  db:
    image: postgres:12
    networks:
      - sonarnet
    environment:
      - POSTGRES_USER=sonar
      - POSTGRES_PASSWORD=sonar
      - POSTGRES_DB=sonar

networks:
  sonarnet:

이후 터미널에서 다음 명령어를 실행한다.

docker-compose up -d

브라우저에서 http://localhost:9000 접속 (초기 계정: admin / admin)
초기 비밀번호 변경 수행
Local Project 생성 $\rightarrow$ Generate Token 발급 (스캐너 인증용)

5.2 프로젝트 설정

프로젝트 루트 경로에 sonar-project.properties 파일을 생성하여 분석 설정을 정의한다.

# 프로젝트 식별 정보
sonar.projectKey=my-awesome-project
sonar.projectName=My Awesome Project
sonar.projectVersion=1.0

# 분석 대상 경로 및 제외 설정
sonar.sources=src
sonar.exclusions=src/**/*.test.js, src/vendor/**

# 언어별 설정 (예: JavaScript/TypeScript)
sonar.javascript.lcov.reportPaths=coverage/lcov.info

# 서버 연결 설정 (CI 환경에서는 환경변수로 대체 가능)
# sonar.host.url=http://localhost:9000
# sonar.login=your_generated_token

6. CI/CD 파이프라인 통합

현대적인 개발 환경에서는 코드가 Push될 때마다 자동으로 분석이 수행되도록 파이프라인에 통합한다.

6.1 GitHub Actions 통합 예시

.github/workflows/sonarqube.yml 파일에 다음과 같이 설정하여 자동 분석을 구현할 수 있다.

name: SonarQube Analysis
on:
  push:
    branches: [ main ]
  pull_request:
    types: [ opened, synchronize, reopened ]

jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 전체 히스토리를 가져와야 정확한 분석 가능

      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          args: >
            -Dsonar.projectKey=my-awesome-project
            -Dsonar.sources=src
            -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info

6.2 파이프라인 구성 전략

PR 분석: Pull Request 단계에서 분석을 수행하여 머지(Merge) 전 결함을 수정하는 'Shift-Left' 전략을 취한다.
빌드 차단: 품질 게이트 실패 시 CI 파이프라인을 중단시켜 결함이 운영 환경으로 전파되는 것을 방지한다.

7. 버전 비교

기능	Community Edition	Developer Edition	Enterprise Edition
기본 정적 분석	지원	지원	지원
다국어 지원	지원	지원	지원
분석 프로젝트 수	무제한	무제한	무제한
분기 커버리지	미지원	지원	지원
PR 분석 및 데코레이션	미지원	지원	지원
포트폴리오 관리	미지원	미지원	지원
보안 핫스팟	기본 탐지 지원	심화 분석 및 관리 지원	심화 분석 및 관리 지원
기술 지원	커뮤니티 포럼	전담 기술 지원	전담 기술 지원

8. 분석 결과 확인

분석이 완료되면 SonarQube 대시보드에서 시각적 리포트를 확인할 수 있다.

SonarQube Dashboard Example

대시보드에서는 프로젝트별 버그 수, 취약점, 코드 커버리지 및 기술 부채 시간이 수치와 그래프로 표시된다. 이를 통해 현재 코드의 건강 상태를 한눈에 파악하고, 어떤 부분에서 리팩토링이나 보안 수정이 시급한지 우선순위를 결정할 수 있다.

9. 도입 효과 및 한계

9.1 도입 효과

코드 표준화: 팀 전체가 동일한 품질 프로필을 공유함으로써 일관된 코딩 스타일 유지.
유지보수 비용 절감: 기술 부채를 가시화하여 조기에 리팩토링함으로써 장기적인 유지보수 비용 감소.
보안 강화: 알려진 보안 취약점을 자동으로 탐지하여 보안 사고 예방.

9.2 한계점 및 보완 방법

런타임 오류 탐지 불가: 정적 분석은 코드의 구조만 보기 때문에, 실제 실행 시 발생하는 메모리 누수나 네트워크 타임아웃 등의 런타임 오류를 잡을 수 없다.
오탐(False Positive): 실제로는 문제가 없으나 규칙상 오류로 판별되는 경우가 존재한다.
보완 방법:
- 단위 테스트(Unit Test): JUnit, PyTest 등을 통해 비즈니스 로직의 정확성을 검증한다.
- 동적 분석(DAST): 실제 실행 중인 애플리케이션을 대상으로 보안 취약점을 점검한다.
- 코드 리뷰: 도구가 잡지 못하는 설계적 결함은 동료 리뷰를 통해 보완한다.

📝 마크다운 원본

이 문서의 마크다운 원본 내용입니다.

# SonarQube

## 1. 개요
**SonarQube**는 소스 코드의 품질과 보안을 자동으로 검사하여 코드의 결함을 찾아내고 관리하는 오픈 소스 기반의 정적 코드 분석(Static Code Analysis) 플랫폼이다.

**정적 코드 분석**이란 프로그램을 실제로 실행하지 않고 소스 코드 자체를 분석하여 잠재적인 버그, 보안 취약점, 코딩 표준 위반 사례를 찾아내는 기법을 의미한다. SonarQube는 소프트웨어 개발 생명주기(SDLC, Software Development Life Cycle) 전반에 걸쳐 코드 리뷰 과정을 자동화함으로써, 개발 초기 단계에서 결함을 발견하고 수정하게 하여 최종 제품의 안정성을 높이는 역할을 수행한다.

## 2. 주요 분석 지표
SonarQube는 코드의 상태를 정량적으로 측정하기 위해 다음과 같은 핵심 지표를 사용한다.

### 2.1 핵심 지표 정의
*   **버그(Bugs):** 코드 실행 시 잘못된 동작을 유발하거나 런타임 오류를 일으킬 가능성이 높은 결함이다.
*   **취약점(Vulnerabilities):** 해커가 악용할 수 있는 보안상의 허점으로, SQL 인젝션이나 크로스 사이트 스크립팅(XSS) 등이 이에 해당한다.
*   **코드 스멜(Code Smells):** 기능적으로는 동작하지만, 유지보수를 어렵게 만드는 설계상의 문제나 가독성이 떨어지는 코드 패턴을 의미한다.
*   **기술 부채(Technical Debt):** 당장의 빠른 구현을 위해 선택한 임시방편적인 코드나 낮은 품질의 코드를 수정하는 데 필요한 예상 시간과 비용을 의미한다.

### 2.2 지표별 비교
| 지표 | 정의 | 위험도 | 영향 범위 | 해결 우선순위 |
| :--- | :--- | :---: | :--- | :---: |
| **버그** | 논리적 오류 및 런타임 결함 | 높음 | 애플리케이션 기능 마비 | 최상 |
| **취약점** | 보안상 허점 및 공격 경로 | 매우 높음 | 데이터 유출 및 시스템 침해 | 최상 |
| **코드 스멜** | 유지보수성 저해 요소 | 낮음 | 개발 생산성 및 가독성 저하 | 보통 |

## 3. 작동 원리 및 아키텍처
SonarQube는 분산된 구조를 통해 코드 스캔부터 결과 리포팅까지의 과정을 처리한다.

### 3.1 워크플로우
1.  **스캔(Scan):** `SonarScanner`가 프로젝트 소스 코드를 읽어 분석 데이터를 생성한다.
2.  **전송(Send):** 생성된 분석 리포트를 HTTP 통신을 통해 `SonarQube Server`로 전송한다.
3.  **처리(Process):** 서버 내의 **Compute Engine**이 큐(Queue)에서 분석 리포트를 가져와 실제 분석을 수행하고, 설정된 규칙(Quality Profile)에 따라 위반 사항을 판별하여 이슈를 생성한다.
4.  **저장 및 표시(Store & Display):** 분석 결과는 `Database`에 저장되며, 사용자는 웹 UI를 통해 대시보드 형태로 결과를 확인한다.

### 3.2 아키텍처 구성 요소
*   **SonarScanner:** 각 언어별(Java, JS, Python 등) 스캐너가 설치된 환경에서 코드를 분석하는 클라이언트 도구이다.
*   **SonarQube Server:** 분석 엔진(Compute Engine), 웹 인터페이스, API 서버를 포함하는 중앙 제어 시스템이다.
*   **Database:** 프로젝트 설정, 분석 이력, 이슈 상태 등을 저장하는 영속성 계층(PostgreSQL, Oracle, Microsoft SQL Server 등 지원)이다.

## 4. 핵심 기능 및 활용
### 4.1 품질 게이트 (Quality Gates)
품질 게이트는 프로젝트가 다음 단계(예: 배포)로 넘어가기 위해 충족해야 하는 **최소한의 품질 기준**이다. 예를 들어 "새로운 코드의 버그가 0개여야 함", "테스트 커버리지가 80% 이상이어야 함"과 같은 조건을 설정하여, 기준 미달 시 빌드를 실패(Fail) 처리함으로써 품질 저하를 원천 차단한다.

### 4.2 품질 프로필 (Quality Profiles)
품질 프로필은 분석 시 적용할 **코딩 규칙의 집합**이다. 언어별로 기본 제공되는 규칙 세트가 있으며, 조직의 코딩 컨벤션에 맞게 특정 규칙을 활성화하거나 비활성화하여 커스텀 프로필을 생성할 수 있다.

### 4.3 다국어 지원
SonarQube는 Java, C#, JavaScript, TypeScript, Python, Go, Kotlin, Swift 등 25개 이상의 주요 프로그래밍 언어를 지원하여 폴리글랏(Polyglot) 환경에서도 통합 관리가 가능하다.

## 5. 설치 및 초기 설정 가이드
SonarQube는 DB 분리가 필수적이므로 Docker Compose를 이용한 설치가 가장 권장된다.

### 5.1 Docker Compose를 이용한 설치
먼저 `docker-compose.yml` 파일을 다음과 같이 작성한다.

```yaml
version: '3'
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - "9000:9000"
    networks:
      - sonarnet
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonar
      - SONAR_JDBC_USERNAME=sonar
      - SONAR_JDBC_PASSWORD=sonar
    depends_on:
      - db

  db:
    image: postgres:12
    networks:
      - sonarnet
    environment:
      - POSTGRES_USER=sonar
      - POSTGRES_PASSWORD=sonar
      - POSTGRES_DB=sonar

networks:
  sonarnet:
```

이후 터미널에서 다음 명령어를 실행한다.
```bash
docker-compose up -d
```

1.  브라우저에서 `http://localhost:9000` 접속 (초기 계정: `admin` / `admin`)
2.  초기 비밀번호 변경 수행
3.  **Local Project** 생성 $\rightarrow$ **Generate Token** 발급 (스캐너 인증용)

### 5.2 프로젝트 설정
프로젝트 루트 경로에 `sonar-project.properties` 파일을 생성하여 분석 설정을 정의한다.

```properties
# 프로젝트 식별 정보
sonar.projectKey=my-awesome-project
sonar.projectName=My Awesome Project
sonar.projectVersion=1.0

# 분석 대상 경로 및 제외 설정
sonar.sources=src
sonar.exclusions=src/**/*.test.js, src/vendor/**

# 언어별 설정 (예: JavaScript/TypeScript)
sonar.javascript.lcov.reportPaths=coverage/lcov.info

# 서버 연결 설정 (CI 환경에서는 환경변수로 대체 가능)
# sonar.host.url=http://localhost:9000
# sonar.login=your_generated_token
```

## 6. CI/CD 파이프라인 통합
현대적인 개발 환경에서는 코드가 Push될 때마다 자동으로 분석이 수행되도록 파이프라인에 통합한다.

### 6.1 GitHub Actions 통합 예시
`.github/workflows/sonarqube.yml` 파일에 다음과 같이 설정하여 자동 분석을 구현할 수 있다.

```yaml
name: SonarQube Analysis
on:
  push:
    branches: [ main ]
  pull_request:
    types: [ opened, synchronize, reopened ]

jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 전체 히스토리를 가져와야 정확한 분석 가능

      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          args: >
            -Dsonar.projectKey=my-awesome-project
            -Dsonar.sources=src
            -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
```

### 6.2 파이프라인 구성 전략
*   **PR 분석:** Pull Request 단계에서 분석을 수행하여 머지(Merge) 전 결함을 수정하는 'Shift-Left' 전략을 취한다.
*   **빌드 차단:** 품질 게이트 실패 시 CI 파이프라인을 중단시켜 결함이 운영 환경으로 전파되는 것을 방지한다.

## 7. 버전 비교

| 기능 | Community Edition | Developer Edition | Enterprise Edition |
| :--- | :---: | :---: | :---: |
| **기본 정적 분석** | 지원 | 지원 | 지원 |
| **다국어 지원** | 지원 | 지원 | 지원 |
| **분석 프로젝트 수** | 무제한 | 무제한 | 무제한 |
| **분기 커버리지** | 미지원 | 지원 | 지원 |
| **PR 분석 및 데코레이션** | 미지원 | 지원 | 지원 |
| **포트폴리오 관리** | 미지원 | 미지원 | 지원 |
| **보안 핫스팟** | 기본 탐지 지원 | 심화 분석 및 관리 지원 | 심화 분석 및 관리 지원 |
| **기술 지원** | 커뮤니티 포럼 | 전담 기술 지원 | 전담 기술 지원 |

## 8. 분석 결과 확인
분석이 완료되면 SonarQube 대시보드에서 시각적 리포트를 확인할 수 있다.

![SonarQube Dashboard Example](https://docs.sonarqube.org/display/docs/SonarQube+Dashboard+Screenshot)

대시보드에서는 프로젝트별 버그 수, 취약점, 코드 커버리지 및 기술 부채 시간이 수치와 그래프로 표시된다. 이를 통해 현재 코드의 건강 상태를 한눈에 파악하고, 어떤 부분에서 리팩토링이나 보안 수정이 시급한지 우선순위를 결정할 수 있다.

## 9. 도입 효과 및 한계
### 9.1 도입 효과
*   **코드 표준화:** 팀 전체가 동일한 품질 프로필을 공유함으로써 일관된 코딩 스타일 유지.
*   **유지보수 비용 절감:** 기술 부채를 가시화하여 조기에 리팩토링함으로써 장기적인 유지보수 비용 감소.
*   **보안 강화:** 알려진 보안 취약점을 자동으로 탐지하여 보안 사고 예방.

### 9.2 한계점 및 보완 방법
*   **런타임 오류 탐지 불가:** 정적 분석은 코드의 구조만 보기 때문에, 실제 실행 시 발생하는 메모리 누수나 네트워크 타임아웃 등의 런타임 오류를 잡을 수 없다.
*   **오탐(False Positive):** 실제로는 문제가 없으나 규칙상 오류로 판별되는 경우가 존재한다.
*   **보완 방법:**
    *   **단위 테스트(Unit Test):** JUnit, PyTest 등을 통해 비즈니스 로직의 정확성을 검증한다.
    *   **동적 분석(DAST):** 실제 실행 중인 애플리케이션을 대상으로 보안 취약점을 점검한다.
    *   **코드 리뷰:** 도구가 잡지 못하는 설계적 결함은 동료 리뷰를 통해 보완한다.

AI 생성 콘텐츠 안내

이 문서는 AI 모델(gemma-4-31b)에 의해 생성된 콘텐츠입니다.

주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.

위키너와나

SonarQube

SonarQube

1. 개요

2. 주요 분석 지표

2.1 핵심 지표 정의

2.2 지표별 비교

3. 작동 원리 및 아키텍처

3.1 워크플로우

3.2 아키텍처 구성 요소

4. 핵심 기능 및 활용

4.1 품질 게이트 (Quality Gates)

4.2 품질 프로필 (Quality Profiles)

4.3 다국어 지원

5. 설치 및 초기 설정 가이드

5.1 Docker Compose를 이용한 설치

5.2 프로젝트 설정

6. CI/CD 파이프라인 통합

6.1 GitHub Actions 통합 예시

6.2 파이프라인 구성 전략

7. 버전 비교

8. 분석 결과 확인

9. 도입 효과 및 한계

9.1 도입 효과

9.2 한계점 및 보완 방법

📝 마크다운 원본

🤔 AI의 사고 과정

이 AI 생성 콘텐츠가 도움이 되었나요?