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

> 파이프라인 상태 모니터링, 워크플로 및 작업 분석, 빌드 로그 분류, 승인이 필요한 파이프라인 제어를 위해 CircleCI를 CloudThinker에 연결합니다

CircleCI 계정을 연결하면 CloudThinker 에이전트가 파이프라인 상태를 모니터링하고, 워크플로 및 작업을 검사하고, 로그에서 실패한 빌드와 테스트를 분류하고, 워크플로 재실행, 파이프라인 트리거, 배포 롤백과 같이 승인이 필요한 제어를 실행할 수 있습니다.

CircleCI는 **Personal API Token**으로 인증합니다. 토큰은 생성한 사용자의 권한을 상속하므로, 에이전트가 접근할 수 있는 범위는 해당 사용자의 프로젝트 접근 권한과 일치합니다.

***

## 사전 요구 사항

* 조사할 조직 및 프로젝트에 접근 권한이 있는 **CircleCI 계정**.
* **Personal API Token**.
* 승인이 필요한 제어의 경우, 토큰의 사용자가 대상 프로젝트에 **트리거/파이프라인 권한**이 필요합니다.

<Info>
  읽기 전용 분석은 표준 Personal API Token으로 작동합니다. 승인이 필요한 제어는 추가로 토큰의 사용자가 대상 프로젝트에 트리거 권한을 가져야 합니다.
</Info>

***

## 설정

<Steps>
  <Step title="Personal API Token 생성">
    CircleCI에서 **사용자 아바타 → User Settings → Personal API Tokens** ([app.circleci.com/settings/user/tokens](https://app.circleci.com/settings/user/tokens))으로 이동하여 **Create New Token**을 클릭합니다.

    * **Token name**: `cloudthinker`
    * **Expiry date**: 수명을 선택하고 교체 계획 수립

    토큰을 즉시 복사하세요 — CircleCI는 한 번만 표시합니다.
  </Step>

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

    * **Token**: 방금 생성한 Personal API Token
    * **Base URL**: CircleCI 클라우드의 경우 `https://circleci.com`, 셀프 호스팅 Server 또는 Standalone의 경우 설치 URL

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

<Warning>
  생성 후 Personal API Token을 즉시 복사하세요. 분실 시 새 토큰을 생성해야 합니다.
</Warning>

***

## 연결 세부 정보

| 필드                      | 설명                                                            | 예시                     |
| ----------------------- | ------------------------------------------------------------- | ---------------------- |
| **CIRCLECI\_TOKEN**     | 연결 인증에 사용되는 Personal API Token                                | —                      |
| **CIRCLECI\_BASE\_URL** | 클라우드의 경우 `https://circleci.com`, 또는 Server나 Standalone 설치 URL | `https://circleci.com` |

<Note>
  CloudThinker는 토큰에서 조직 및 팔로우하는 프로젝트를 확인하므로 CircleCI 클라우드에서는 수동 조직 또는 프로젝트 ID 구성이 필요하지 않습니다.
</Note>

***

## 필수 권한

Personal API Token은 생성한 사용자의 접근 권한을 상속합니다. 읽기 작업은 사용자가 대상 프로젝트를 볼 수 있는 토큰이면 작동합니다. 제어 작업은 추가로 토큰의 사용자가 프로젝트에 **트리거/파이프라인 권한**을 가져야 하며 CloudThinker의 명시적인 [승인](/ko/guide/approval)도 필요합니다.

<Tip>
  최소 권한 원칙을 따르세요. CloudThinker에 필요한 프로젝트 접근 권한만 있는 사용자 아래에서 토큰을 생성하고, 가드레일을 제거하는 대신 제어 작업을 승인이 필요한 상태로 유지하세요.
</Tip>

***

## 에이전트 기능

연결 후 에이전트는 CircleCI 프로젝트, 파이프라인, 로그에 읽기 접근 권한을 갖습니다.

| 기능              | 설명                                                            |
| --------------- | ------------------------------------------------------------- |
| **프로젝트 탐색**     | 팔로우하는 프로젝트 목록 조회 및 활성 조직 확인                                   |
| **파이프라인 상태**    | 프로젝트의 최신 파이프라인 상태 검사                                          |
| **워크플로 및 작업**   | 파이프라인의 워크플로 및 작업 검토                                           |
| **빌드 및 테스트 로그** | 실패 분류를 위한 빌드 및 테스트 출력 가져오기                                    |
| **파이프라인 제어**    | 파이프라인 실행, 워크플로 재실행, 평가 테스트 실행, 배포 롤백, 프롬프트 템플릿 생성 — **승인 필요** |

### 연결 확인

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

### 예시 프롬프트

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

많은 프로젝트가 있는 조직의 경우, 에이전트가 집중적인 결과를 반환하도록 단일 프로젝트로 요청 범위를 좁히세요.

***

## 문제 해결

<Accordion title="401 또는 403 Unauthorized">
  토큰이 누락되었거나, 만료되었거나, 취소되었습니다. 새 Personal API Token을 생성하고 CircleCI 연결을 다시 연결하세요.
</Accordion>

<Accordion title="연결은 되지만 프로젝트가 나타나지 않음">
  토큰의 사용자가 팔로우하는 프로젝트가 없거나 확인된 조직이 잘못되었습니다. CircleCI에서 적어도 하나의 프로젝트를 팔로우한 후 탐색을 다시 실행하세요.
</Accordion>

<Accordion title="권한 오류로 제어 작업 실패">
  토큰에 프로젝트에 대한 트리거/파이프라인 권한이 없습니다. 해당 프로젝트에 트리거 권한이 있는 사용자 아래에서 토큰을 재생성하고 다시 연결하세요.
</Accordion>

<Accordion title="사용량 데이터 또는 컴포넌트 버전이 반환되지 않음">
  사용량 API는 유료 플랜 전용이며, 컴포넌트 버전은 Server 또는 Standalone 전용입니다. 플랜 티어를 확인하세요 — 이는 티어 제한이며 구성 오류가 아닙니다.
</Accordion>

<Accordion title="셀프 호스팅 서버에서 404 또는 인증 오류 반환">
  **CIRCLECI\_BASE\_URL**이 여전히 `https://circleci.com`으로 설정되어 있습니다. Server 또는 Standalone 설치 URL로 변경하고 다시 연결하세요.
</Accordion>

<Accordion title="롤백 작업이 실행되지 않음">
  배포 롤백은 프로덕션에 영향을 미치고, 승인이 필요하며, Server 또는 Standalone에서만 사용 가능합니다 (클라우드 전용 조직에서는 불가). 메시지가 표시될 때 작업을 승인하고, 설치가 이를 지원하는지 확인하세요.
</Accordion>

***

## 보안

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

- **제어에 승인 필요** — 가드레일을 제거하는 대신 파이프라인, 재실행, 롤백 및 기타 쓰기 작업을 승인이 필요한 상태로 유지하세요.
- **올바른 기본 URL** — 클라우드의 경우 `https://circleci.com`을, 셀프 호스팅 Server 또는 Standalone의 경우 설치 URL을 사용하세요.

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="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="/ko/guide/connections/jenkins" width="24" height="24" data-path="images/icons/jenkins.svg">
    빌드 파이프라인 모니터링 및 작업 분석
  </Card>

  <Card title="승인" icon="shield-check" href="/ko/guide/approval">
    승인이 필요한 작업의 작동 방식
  </Card>
</CardGroup>