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

> CloudThinker と CircleCI を接続して、パイプライン状態の監視、ワークフローとジョブの分析、ビルドログのトリアージ、承認ゲートのパイプライン制御を実現する

CircleCI アカウントを接続することで、CloudThinker エージェントがパイプライン状態の監視、ワークフローとジョブの調査、失敗したビルドとテストのログトリアージ、ワークフローの再実行・パイプラインのトリガー・デプロイのロールバックなど承認ゲートが必要なコントロールの実行を行えるようになります。

CircleCI は**個人 API トークン**で認証します。トークンはそれを作成したユーザーの権限を継承するため、エージェントがアクセスできる範囲はそのユーザーのプロジェクトアクセスに一致します。

***

## 前提条件

* 調査したい組織とプロジェクトへのアクセスがある **CircleCI アカウント**。
* **個人 API トークン**。
* 承認ゲートコントロールを使用する場合は、トークンのユーザーが対象プロジェクトで**トリガー/パイプライン権限**を持っている必要があります。

<Info>
  読み取り専用分析は標準の個人 API トークンで機能します。承認ゲートコントロールには、トークンのユーザーが対象プロジェクトでトリガー権限を持っていることも必要です。
</Info>

***

## セットアップ

<Steps>
  <Step title="個人 API トークンを作成する">
    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**: 作成した個人 API トークン
    * **Base URL**: CircleCI クラウドの場合は `https://circleci.com`、セルフホスト Server または Standalone の場合はインストール URL

    **Connect** をクリックします。CloudThinker が認証情報を検証し、**Connected** ステータスを表示します。
  </Step>
</Steps>

<Warning>
  個人 API トークンは作成直後にコピーしてください。紛失した場合は新しいトークンを作成する必要があります。
</Warning>

***

## 接続の詳細

| フィールド                   | 説明                                                                | 例                      |
| ----------------------- | ----------------------------------------------------------------- | ---------------------- |
| **CIRCLECI\_TOKEN**     | 接続の認証に使用する個人 API トークン                                             | —                      |
| **CIRCLECI\_BASE\_URL** | クラウドの場合は `https://circleci.com`、Server または Standalone のインストール URL | `https://circleci.com` |

<Note>
  CloudThinker はトークンから組織とフォロー中のプロジェクトを解決するため、CircleCI クラウドでは手動での組織 ID やプロジェクト ID の設定は不要です。
</Note>

***

## 必要な権限

個人 API トークンはそれを作成したユーザーのアクセスを継承します。読み取り操作は対象プロジェクトを参照できるユーザーのトークンであれば機能します。コントロール操作には、トークンのユーザーがプロジェクトで**トリガー/パイプライン権限**を持っていること **および** CloudThinker での明示的な[承認](/ja/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">
  トークンが欠落、期限切れ、または失効しています。新しい個人 API トークンを作成して CircleCI 接続を再接続してください。
</Accordion>

<Accordion title="接続テストは成功するがプロジェクトが表示されない">
  トークンのユーザーがプロジェクトをフォローしていないか、解決された組織が間違っています。CircleCI で少なくとも 1 つのプロジェクトをフォローしてから、検出を再実行してください。
</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="/ja/guide/connections/jenkins" width="24" height="24" data-path="images/icons/jenkins.svg">
    ビルドパイプライン監視とジョブ分析
  </Card>

  <Card title="承認" icon="shield-check" href="/ja/guide/approval">
    承認ゲートアクションの仕組み
  </Card>
</CardGroup>