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.

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.

---

Setup

1. Create a Personal API Token

   In CircleCI, go to your user avatar → User Settings → Personal API Tokens (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.

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

Copy the Personal API Token immediately after creation. You’ll need to create a new token if it’s lost.

---

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

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

---

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 in CloudThinker.

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.

---

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

@alex list my followed CircleCI projects and show the latest pipeline status for one of them

Example prompts

@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

401 or 403 Unauthorized

The token is missing, expired, or revoked. Create a fresh Personal API Token and reconnect the CircleCI connection.

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.

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.

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.

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.

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.

---

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

Jenkins Connection

Build pipeline monitoring and job analysis

Approval

How approval-gated actions work