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

# CircleCI

> Kết nối CircleCI với CloudThinker để giám sát trạng thái pipeline, phân tích workflow và job, phân loại build log và điều khiển pipeline được kiểm soát bởi phê duyệt

Kết nối tài khoản CircleCI của bạn để cho phép các agent CloudThinker giám sát trạng thái pipeline, kiểm tra workflow và job, phân loại build và test thất bại từ log, cũng như chạy các thao tác điều khiển được kiểm soát bởi phê duyệt như chạy lại workflow, kích hoạt pipeline hoặc rollback deployment.

CircleCI xác thực bằng **Personal API Token**. Token kế thừa quyền của người tạo, vì vậy những gì agent có thể truy cập phản ánh quyền truy cập project của người dùng đó.

***

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

* Một **tài khoản CircleCI** với quyền truy cập vào tổ chức và các project bạn muốn điều tra.
* Một **Personal API Token**.
* Với các thao tác điều khiển được kiểm soát bởi phê duyệt, người dùng của token cần có **quyền trigger/pipeline** trên project mục tiêu.

<Info>
  Phân tích chỉ đọc hoạt động với Personal API Token tiêu chuẩn. Các thao tác điều khiển được kiểm soát bởi phê duyệt bổ sung yêu cầu người dùng của token có quyền trigger trên project.
</Info>

***

## Thiết lập

<Steps>
  <Step title="Tạo Personal API Token">
    Trong CircleCI, vào **user avatar → User Settings → Personal API Tokens** ([app.circleci.com/settings/user/tokens](https://app.circleci.com/settings/user/tokens)) và nhấn **Create New Token**:

    * **Token name**: `cloudthinker`
    * **Expiry date**: chọn thời hạn và lên kế hoạch xoay vòng

    Sao chép token ngay lập tức — CircleCI chỉ hiển thị một lần.
  </Step>

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

    * **Token**: Personal API Token bạn vừa tạo
    * **Base URL**: `https://circleci.com` cho CircleCI cloud, hoặc URL cài đặt của bạn cho Server hoặc Standalone tự lưu trữ

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

<Warning>
  Sao chép Personal API Token ngay sau khi tạo. Bạn cần tạo token mới nếu mất.
</Warning>

***

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

| Trường                  | Mô tả                                                                            | Ví dụ                  |
| ----------------------- | -------------------------------------------------------------------------------- | ---------------------- |
| **CIRCLECI\_TOKEN**     | Personal API Token dùng để xác thực kết nối                                      | —                      |
| **CIRCLECI\_BASE\_URL** | `https://circleci.com` cho cloud, hoặc URL cài đặt Server hay Standalone của bạn | `https://circleci.com` |

<Note>
  CloudThinker tự động xác định tổ chức và các project đang theo dõi từ token, nên không cần cấu hình thủ công org hay project ID trên CircleCI cloud.
</Note>

***

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

Personal API Token kế thừa quyền truy cập của người tạo. Các thao tác đọc hoạt động với bất kỳ token nào có người dùng có thể xem project mục tiêu. Các thao tác điều khiển bổ sung yêu cầu người dùng của token có **quyền trigger/pipeline** trên project **và** [phê duyệt](/vi/guide/approval) rõ ràng trong CloudThinker.

<Tip>
  Tuân theo nguyên tắc ít quyền nhất: tạo token dưới tài khoản người dùng chỉ có quyền truy cập project mà CloudThinker cần, và giữ các thao tác điều khiển được kiểm soát bởi phê duyệt thay vì bỏ đi lớp bảo vệ này.
</Tip>

***

## Khả năng của Agent

Sau khi kết nối, các agent có quyền đọc đối với các project, pipeline và log CircleCI của bạn.

| Khả năng                | Mô tả                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Khám phá project**    | Liệt kê các project đang theo dõi và xác định tổ chức đang hoạt động                                                       |
| **Trạng thái pipeline** | Kiểm tra trạng thái pipeline mới nhất của một project                                                                      |
| **Workflow & job**      | Xem xét các workflow và job của chúng trong một pipeline                                                                   |
| **Build & test log**    | Lấy output build và test để phân loại lỗi                                                                                  |
| **Điều khiển pipeline** | Chạy pipeline, chạy lại workflow, chạy evaluation test, rollback deployment và tạo prompt template — **yêu cầu phê duyệt** |

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

```text theme={null}
@alex list my followed CircleCI projects and show the latest pipeline status for one of them
```

### Ví dụ prompt

```text theme={null}
@alex check the latest CircleCI pipeline status for my main project and #report any failures
@alex the latest workflow failed — pull the build and test logs, find the error, and #recommend a fix
@alex list my followed CircleCI projects and their most recent pipeline status #dashboard
```

Với các tổ chức có nhiều project, hãy giới hạn yêu cầu theo một project duy nhất để agent trả về kết quả tập trung.

***

## Khắc phục sự cố

<Accordion title="401 hoặc 403 Unauthorized">
  Token bị thiếu, đã hết hạn hoặc bị thu hồi. Tạo một Personal API Token mới và kết nối lại kết nối CircleCI.
</Accordion>

<Accordion title="Kết nối thành công nhưng không có project nào xuất hiện">
  Người dùng của token không theo dõi project nào, hoặc tổ chức được xác định không đúng. Theo dõi ít nhất một project trong CircleCI, rồi chạy lại khám phá.
</Accordion>

<Accordion title="Thao tác điều khiển thất bại do lỗi quyền hạn">
  Token thiếu quyền trigger/pipeline trên project. Tạo lại token dưới tài khoản người dùng có quyền trigger trên project đó và kết nối lại.
</Accordion>

<Accordion title="Dữ liệu sử dụng hoặc phiên bản component không trả về kết quả">
  API sử dụng chỉ dành cho gói trả phí, và phiên bản component chỉ có trên Server hoặc Standalone. Xác nhận cấp gói của bạn — đây là giới hạn theo cấp, không phải lỗi cấu hình.
</Accordion>

<Accordion title="Server tự lưu trữ trả về 404 hoặc lỗi xác thực">
  **CIRCLECI\_BASE\_URL** vẫn đang được đặt là `https://circleci.com`. Đặt thành URL cài đặt Server hoặc Standalone của bạn và kết nối lại.
</Accordion>

<Accordion title="Thao tác rollback không chạy">
  Rollback deployment là thao tác ảnh hưởng đến production, được kiểm soát bởi phê duyệt và chỉ khả dụng trên Server hoặc Standalone — không phải các tổ chức chỉ dùng cloud. Phê duyệt thao tác khi được nhắc và xác nhận cài đặt của bạn hỗ trợ tính năng này.
</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.

- **Phê duyệt cho các thao tác điều khiển** — giữ các thao tác pipeline, chạy lại, rollback và các thao tác ghi khác được kiểm soát bởi phê duyệt thay vì bỏ đi lớp bảo vệ này.
- **Base URL đúng** — dùng `https://circleci.com` cho cloud, hoặc URL cài đặt của bạn cho Server hoặc Standalone tự lưu trữ.

***

## Liên quan

<CardGroup cols={2}>
  <Card title="Kết nối Jenkins" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/jenkins.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=871f9df2f5553b663f1b5c33f11bf5da" href="/vi/guide/connections/jenkins" width="24" height="24" data-path="images/icons/jenkins.svg">
    Giám sát build pipeline và phân tích job
  </Card>

  <Card title="Phê duyệt" icon="shield-check" href="/vi/guide/approval">
    Cách thức hoạt động của các hành động được kiểm soát bởi phê duyệt
  </Card>
</CardGroup>