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

> Connect CircleCI to CloudThinker for pipeline status monitoring, workflow and job analysis, build log triage, and approval-gated pipeline controls

Connect your CircleCI account to enable CloudThinker agents to monitor pipeline status, inspect workflows and jobs, triage failing builds and tests from logs, and run approval-gated controls like rerunning a workflow, triggering a pipeline, or rolling back a deployment.

CircleCI authenticates with a **Personal API Token**. The token inherits the permissions of the user who created it, so what the agent can reach matches that user's project access.

***

## Prerequisites

* A **CircleCI account** with access to the organization and projects you want to investigate.
* A **Personal API Token**.
* For the approval-gated controls, the token's user needs **trigger/pipeline permission** on the target project.

<Info>
  Read-only analysis works with a standard Personal API Token. The approval-gated controls additionally require the token's user to have trigger permission on the target project.
</Info>

***

## Setup

<Steps>
  <Step title="Create a Personal API Token">
    In CircleCI, go to your **user avatar → User Settings → Personal API Tokens** ([app.circleci.com/settings/user/tokens](https://app.circleci.com/settings/user/tokens)) and click **Create New Token**:

    * **Token name**: `cloudthinker`
    * **Expiry date**: choose a lifetime and plan to rotate

    Copy the token immediately — CircleCI shows it only once.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → CircleCI** and enter:

    * **Token**: the Personal API Token you just created
    * **Base URL**: `https://circleci.com` for CircleCI cloud, or your install URL for self-hosted Server or Standalone

    Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Copy the Personal API Token immediately after creation. You'll need to create a new token if it's lost.
</Warning>

***

## Connection details

| Field                   | Description                                                                | Example                |
| ----------------------- | -------------------------------------------------------------------------- | ---------------------- |
| **CIRCLECI\_TOKEN**     | Personal API Token used to authenticate the connection                     | —                      |
| **CIRCLECI\_BASE\_URL** | `https://circleci.com` for cloud, or your Server or Standalone install URL | `https://circleci.com` |

<Note>
  CloudThinker resolves your organization and followed projects from the token, so no manual org or project ID configuration is required on CircleCI cloud.
</Note>

***

## Required permissions

The Personal API Token inherits the access of the user who created it. Read operations work with any token whose user can see the target projects. The control operations additionally require the token's user to have **trigger/pipeline permission** on the project **and** explicit [approval](/guide/approval) in CloudThinker.

<Tip>
  Follow least privilege: create the token under a user with only the project access CloudThinker needs, and keep control operations approval-gated rather than removing the guardrail.
</Tip>

***

## Agent capabilities

Once connected, agents have read access to your CircleCI projects, pipelines, and logs.

| Capability            | Description                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Project discovery** | List followed projects and resolve the active organization                                                                       |
| **Pipeline status**   | Inspect the latest pipeline status for a project                                                                                 |
| **Workflows & jobs**  | Review workflows and their jobs for a pipeline                                                                                   |
| **Build & test logs** | Fetch build and test output for failure triage                                                                                   |
| **Pipeline controls** | Run pipelines, rerun workflows, run evaluation tests, roll back deployments, and create prompt templates — **requires approval** |

### Verify the connection

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

### Example prompts

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

For organizations with many projects, scope requests to a single project so the agent returns focused results.

***

## Troubleshooting

<Accordion title="401 or 403 Unauthorized">
  The token is missing, expired, or revoked. Create a fresh Personal API Token and reconnect the CircleCI connection.
</Accordion>

<Accordion title="Connection tests but no projects appear">
  The token's user follows no projects, or the resolved organization is wrong. Follow at least one project in CircleCI, then re-run discovery.
</Accordion>

<Accordion title="Control actions fail with a permission error">
  The token lacks trigger/pipeline permission on the project. Regenerate the token under a user who has trigger rights on that project and reconnect.
</Accordion>

<Accordion title="Usage data or component versions return nothing">
  The usage API is paid-plan only, and component versions are Server or Standalone only. Confirm your plan tier — these are tier-gated, not a configuration error.
</Accordion>

<Accordion title="Self-hosted server returns 404 or auth errors">
  **CIRCLECI\_BASE\_URL** is still set to `https://circleci.com`. Set it to your Server or Standalone install URL and reconnect.
</Accordion>

<Accordion title="Rollback action did not run">
  Rolling back a deployment is production-destructive, approval-gated, and available only on Server or Standalone — not cloud-only organizations. Approve the action when prompted, and confirm your install supports it.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Approval for controls** — keep pipeline, rerun, rollback, and other write actions approval-gated rather than removing the guardrail.
- **Correct base URL** — use `https://circleci.com` for cloud, or your install URL for self-hosted Server or Standalone.

***

## Related

<CardGroup cols={2}>
  <Card title="Jenkins Connection" 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="/guide/connections/jenkins" width="24" height="24" data-path="images/icons/jenkins.svg">
    Build pipeline monitoring and job analysis
  </Card>

  <Card title="Approval" icon="shield-check" href="/guide/approval">
    How approval-gated actions work
  </Card>
</CardGroup>