> ## 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

> Kết nối SonarQube với CloudThinker để phân tích chất lượng code liên tục, quét bảo mật và theo dõi nợ kỹ thuật

Kết nối instance SonarQube của bạn để cho phép các agent CloudThinker phân tích chất lượng code, xem xét các điểm nóng bảo mật và giám sát trạng thái quality gate trên các project của bạn. CloudThinker sử dụng MCP server chính thức của SonarSource và xác thực bằng **user token**.

***

## Nền tảng được hỗ trợ

| Nền tảng             | Hỗ trợ         |
| -------------------- | -------------- |
| **SonarQube Cloud**  | Tất cả tổ chức |
| **SonarQube Server** | 2025.4 trở lên |

***

## Điều kiện tiên quyết

* Một tổ chức **SonarQube Cloud** hoặc một instance **SonarQube Server** đang chạy phiên bản 2025.4 trở lên.
* Một **user token** được tạo từ **My Account → Security → Generate Tokens**.
* Quyền **Browse** trên các project mà CloudThinker cần phân tích.

<Info>
  CloudThinker sử dụng MCP server chính thức của SonarSource, yêu cầu SonarQube Server 2025.4+ hoặc SonarQube Cloud.
</Info>

***

## Thiết lập

<Tabs>
  <Tab title="SonarQube Cloud">
    <Steps>
      <Step title="Tạo token">
        Vào [SonarQube Cloud](https://sonarcloud.io/) → **My Account → Security → Generate Tokens**:

        * **Name**: `cloudthinker`
        * **Type**: `User Token`
        * **Expires in**: đặt thời hạn phù hợp

        Sao chép token — sẽ không được hiển thị lại.
      </Step>

      <Step title="Tìm khóa tổ chức của bạn">
        Vào **My Organizations** và ghi lại khóa tổ chức từ URL:

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

      <Step title="Thêm kết nối trong CloudThinker">
        Điều hướng đến **Connections → SonarQube** và nhập:

        * **Token**: token bạn vừa tạo
        * **Deployment Type**: chọn **SonarQube Cloud**
        * **Organization**: khóa tổ chức của bạn

        Nhấp **Connect**. CloudThinker xác minh thông tin xác thực và hiển thị trạng thái **Connected**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SonarQube Server (tự lưu trữ)">
    <Steps>
      <Step title="Tạo token">
        Vào instance SonarQube của bạn → **My Account → Security → Generate Tokens**:

        * **Name**: `cloudthinker`
        * **Type**: `User Token`
        * **Expires in**: đặt thời hạn phù hợp

        Sao chép token — sẽ không được hiển thị lại.
      </Step>

      <Step title="Tìm URL máy chủ của bạn">
        URL SonarQube Server của bạn là địa chỉ của instance, ví dụ: `https://sonarqube.your-domain.com`.
      </Step>

      <Step title="Thêm kết nối trong CloudThinker">
        Điều hướng đến **Connections → SonarQube** và nhập:

        * **Token**: token bạn vừa tạo
        * **Deployment Type**: chọn **SonarQube Server**
        * **Server URL**: URL instance SonarQube của bạn

        Nhấp **Connect**. CloudThinker xác minh thông tin xác thực và hiển thị trạng thái **Connected**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  Sao chép token ngay sau khi tạo. SonarQube sẽ không hiển thị lại, và bạn cần tạo token mới nếu bị mất.
</Warning>

***

## Chi tiết kết nối

| Trường                          | Mô tả                                 | Ví dụ                               |
| ------------------------------- | ------------------------------------- | ----------------------------------- |
| **SONARQUBE\_TOKEN**            | User token để xác thực                | `squ_xxxxx...`                      |
| **SONARQUBE\_DEPLOYMENT\_TYPE** | `cloud` hoặc `self_hosted`            | `cloud`                             |
| **SONARQUBE\_ORG**              | Khóa tổ chức (chỉ dành cho Cloud)     | `my-org`                            |
| **SONARQUBE\_URL**              | URL máy chủ (chỉ dành cho tự lưu trữ) | `https://sonarqube.your-domain.com` |

***

## Quyền hạn cần thiết

* Quyền **Browse** trên các project bạn muốn CloudThinker phân tích
* Quyền **Execute Analysis** để kích hoạt quét

<Tip>
  Tuân thủ nguyên tắc đặc quyền tối thiểu: quyền Browse là đủ cho việc phân tích chỉ đọc. Chỉ thêm Administer và Create Projects nếu CloudThinker cần quản lý quality gate hoặc đưa project mới vào hệ thống.
</Tip>

***

## Khả năng của agent

Sau khi kết nối, các agent có thể truy vấn dữ liệu chất lượng code trên các project SonarQube của bạn.

| Khả năng              | Mô tả                                                     |
| --------------------- | --------------------------------------------------------- |
| **Duyệt project**     | Liệt kê và kiểm tra tất cả project trong tổ chức của bạn  |
| **Phân tích vấn đề**  | Truy xuất và phân loại bug, lỗ hổng bảo mật và code smell |
| **Quality gate**      | Kiểm tra trạng thái quality gate trên các project         |
| **Điểm nóng bảo mật** | Xem xét và ưu tiên hóa các điểm nóng bảo mật              |
| **Trùng lặp code**    | Phân tích số liệu trùng lặp code                          |
| **Số liệu code**      | Kiểm tra độ phủ, độ phức tạp và xếp hạng khả năng bảo trì |

### Xác minh kết nối

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

### Các lệnh mẫu

```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
```

***

## Xử lý sự cố

<Accordion title="Xác thực thất bại">
  Token không chính xác, đã hết hạn hoặc bị thu hồi. Xác nhận loại token là `User Token`, tạo token mới nếu cần và cập nhật kết nối.
</Accordion>

<Accordion title="Không tìm thấy tổ chức (Cloud)">
  Khóa tổ chức không chính xác, hoặc tài khoản không phải thành viên của tổ chức đó. Xác nhận khóa từ **My Organizations** trong SonarQube Cloud và kiểm tra tư cách thành viên.
</Accordion>

<Accordion title="Không thể kết nối tới máy chủ (tự lưu trữ)">
  URL SonarQube sai hoặc instance không thể truy cập từ CloudThinker. Xác minh URL, kiểm tra quy tắc tường lửa và xác nhận dịch vụ SonarQube đang chạy.
</Accordion>

<Accordion title="Không thấy project nào">
  Chủ sở hữu token thiếu quyền Browse trên các project. Kiểm tra cài đặt hiển thị project (công khai hoặc riêng tư) và cấp quyền Browse cho các project mà CloudThinker cần phân tích.
</Accordion>

***

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Chỉ dùng HTTPS** — luôn sử dụng HTTPS cho các instance tự lưu trữ để bảo vệ token trong quá trình truyền.
- **Loại User Token** — sử dụng `User Token`, không phải Global Analysis Token, để giới hạn phạm vi token theo những gì CloudThinker cần.

***

## Liên quan

<CardGroup cols={2}>
  <Card title="Kết nối 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="/vi/guide/connections/elasticsearch" width="24" height="24" data-path="images/icons/elasticsearch.svg">
    Tìm kiếm log chất lượng code
  </Card>

  <Card title="Kết nối 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="/vi/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    Trực quan hóa số liệu chất lượng code
  </Card>
</CardGroup>