> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SonarQube

> SonarQube를 CloudThinker에 연결하여 지속적인 코드 품질 분석, 보안 스캔, 기술 부채 추적을 수행합니다

SonarQube 인스턴스를 연결하면 CloudThinker 에이전트가 코드 품질을 분석하고, 보안 핫스팟을 검토하며, 프로젝트 전반의 품질 게이트 상태를 모니터링할 수 있습니다. CloudThinker는 공식 SonarSource MCP 서버를 사용하며 **사용자 토큰**으로 인증합니다.

***

## 지원 플랫폼

| 플랫폼                  | 지원        |
| -------------------- | --------- |
| **SonarQube Cloud**  | 모든 조직     |
| **SonarQube Server** | 2025.4 이상 |

***

## 사전 요구사항

* **SonarQube Cloud** 조직 또는 버전 2025.4 이상을 실행하는 **SonarQube Server** 인스턴스.
* **My Account → Security → Generate Tokens**에서 생성한 **사용자 토큰**.
* CloudThinker가 분석할 프로젝트에 대한 **Browse** 권한.

<Info>
  CloudThinker는 공식 SonarSource MCP 서버를 사용하며, SonarQube Server 2025.4 이상 또는 SonarQube Cloud가 필요합니다.
</Info>

***

## 설정

<Tabs>
  <Tab title="SonarQube Cloud">
    <Steps>
      <Step title="토큰 생성">
        [SonarQube Cloud](https://sonarcloud.io/)로 이동하여 **My Account → Security → Generate Tokens**를 클릭합니다:

        * **Name**: `cloudthinker`
        * **Type**: `User Token`
        * **Expires in**: 적절한 기간 설정

        토큰을 복사합니다 — 다시 표시되지 않습니다.
      </Step>

      <Step title="조직 키 확인">
        **My Organizations**로 이동하여 URL에서 조직 키를 확인합니다:

        ```
        https://sonarcloud.io/organizations/YOUR_ORG_KEY
        ```
      </Step>

      <Step title="CloudThinker에서 연결 추가">
        **Connections → SonarQube**로 이동하여 다음을 입력합니다:

        * **Token**: 생성한 토큰
        * **Deployment Type**: **SonarQube Cloud** 선택
        * **Organization**: 조직 키

        **Connect**를 클릭합니다. CloudThinker가 자격 증명을 확인하고 **Connected** 상태를 표시합니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SonarQube Server (자체 호스팅)">
    <Steps>
      <Step title="토큰 생성">
        SonarQube 인스턴스로 이동하여 **My Account → Security → Generate Tokens**를 클릭합니다:

        * **Name**: `cloudthinker`
        * **Type**: `User Token`
        * **Expires in**: 적절한 기간 설정

        토큰을 복사합니다 — 다시 표시되지 않습니다.
      </Step>

      <Step title="서버 URL 확인">
        SonarQube Server URL은 인스턴스의 주소입니다(예: `https://sonarqube.your-domain.com`).
      </Step>

      <Step title="CloudThinker에서 연결 추가">
        **Connections → SonarQube**로 이동하여 다음을 입력합니다:

        * **Token**: 생성한 토큰
        * **Deployment Type**: **SonarQube Server** 선택
        * **Server URL**: SonarQube 인스턴스 URL

        **Connect**를 클릭합니다. CloudThinker가 자격 증명을 확인하고 **Connected** 상태를 표시합니다.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  토큰 생성 직후 바로 복사하세요. SonarQube는 토큰을 다시 표시하지 않으며, 분실한 경우 새 토큰을 생성해야 합니다.
</Warning>

***

## 연결 세부 정보

| 필드                              | 설명                       | 예시                                  |
| ------------------------------- | ------------------------ | ----------------------------------- |
| **SONARQUBE\_TOKEN**            | 인증용 사용자 토큰               | `squ_xxxxx...`                      |
| **SONARQUBE\_DEPLOYMENT\_TYPE** | `cloud` 또는 `self_hosted` | `cloud`                             |
| **SONARQUBE\_ORG**              | 조직 키 (Cloud 전용)          | `my-org`                            |
| **SONARQUBE\_URL**              | 서버 URL (자체 호스팅 전용)       | `https://sonarqube.your-domain.com` |

***

## 필요 권한

* CloudThinker가 분석할 프로젝트에 대한 **Browse** 권한
* 스캔 트리거를 위한 **Execute Analysis** 권한

<Tip>
  최소 권한 원칙을 따르세요: 읽기 전용 분석에는 Browse 권한으로 충분합니다. CloudThinker가 품질 게이트를 관리하거나 새 프로젝트를 온보딩해야 하는 경우에만 Administer와 Create Projects를 추가하세요.
</Tip>

***

## 에이전트 기능

연결 후 에이전트는 SonarQube 프로젝트 전반의 코드 품질 데이터를 조회할 수 있습니다.

| 기능          | 설명                     |
| ----------- | ---------------------- |
| **프로젝트 탐색** | 조직의 모든 프로젝트 목록 조회 및 검사 |
| **이슈 분석**   | 버그, 취약점, 코드 스멜 검색 및 분류 |
| **품질 게이트**  | 프로젝트 전반의 품질 게이트 상태 확인  |
| **보안 핫스팟**  | 보안 핫스팟 검토 및 우선순위 지정    |
| **코드 중복**   | 코드 중복 메트릭 분석           |
| **코드 메트릭**  | 커버리지, 복잡도, 유지보수성 등급 검사 |

### 연결 확인

```text theme={null}
@oliver list all SonarQube projects and report quality gate statuses
```

### 예시 프롬프트

```text theme={null}
@oliver analyze code quality metrics across all projects and #report quality gate statuses
@oliver review all security hotspots and categorize them by risk level
@oliver list all blocker and critical severity issues broken down by type
```

***

## 트러블슈팅

<Accordion title="인증 실패">
  토큰이 잘못되었거나 만료되었거나 폐기되었습니다. 토큰 유형이 `User Token`인지 확인하고, 필요한 경우 새 토큰을 생성하여 연결을 업데이트합니다.
</Accordion>

<Accordion title="조직을 찾을 수 없음 (Cloud)">
  조직 키가 올바르지 않거나 계정이 해당 조직의 구성원이 아닙니다. SonarQube Cloud의 **My Organizations**에서 키를 확인하고 구성원 자격을 검증합니다.
</Accordion>

<Accordion title="서버에 접근할 수 없음 (자체 호스팅)">
  SonarQube URL이 잘못되었거나 CloudThinker에서 인스턴스에 접근할 수 없습니다. URL을 확인하고, 방화벽 규칙을 점검하며, SonarQube 서비스가 실행 중인지 확인합니다.
</Accordion>

<Accordion title="프로젝트가 표시되지 않음">
  토큰 소유자가 프로젝트에 Browse 권한이 없습니다. 프로젝트 가시성 설정(공개 vs. 비공개)을 확인하고, CloudThinker가 분석해야 하는 프로젝트에 Browse 권한을 부여합니다.
</Accordion>

***

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **HTTPS만 사용** — 자체 호스팅 인스턴스에서는 항상 HTTPS를 사용하여 전송 중인 토큰을 보호합니다.
- **사용자 토큰 유형** — 전역 분석 토큰 대신 `User Token`을 사용하여 CloudThinker에 필요한 범위로 토큰 범위를 제한합니다.

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="Elasticsearch 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/elasticsearch.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c7389cfcd0bc8d303aeeb68bd19199ca" href="/ko/guide/connections/elasticsearch" width="24" height="24" data-path="images/icons/elasticsearch.svg">
    코드 품질 로그 검색
  </Card>

  <Card title="Grafana 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/grafana.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c1329049025cd3c3a0909b400baef7be" href="/ko/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    코드 품질 메트릭 시각화
  </Card>
</CardGroup>