Skip to main content
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 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

FieldDescriptionExample
CIRCLECI_TOKENPersonal API Token used to authenticate the connection—
CIRCLECI_BASE_URLhttps://circleci.com for cloud, or your Server or Standalone install URLhttps://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.
CapabilityDescription
Project DiscoveryList followed projects and resolve the active organization
Pipeline StatusInspect the latest pipeline status for a project
Workflows & JobsReview workflows and their jobs for a pipeline
Build & Test LogsFetch build and test output for failure triage
Pipeline ControlsRun 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 #flag 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 #visualize as a table
@alex rerun the failed workflow on my staging pipeline
For organizations with many projects, scope requests to a single project so the agent returns focused results.

​
Troubleshooting

The token is missing, expired, or revoked. Create a fresh Personal API Token and reconnect the CircleCI connection.
The token’s user follows no projects, or the resolved organization is wrong. Follow at least one project in CircleCI, then re-run discovery.
The token lacks trigger/pipeline permission on the project. Regenerate the token under a user who has trigger rights on that project and reconnect.
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.
CIRCLECI_BASE_URL is still set to https://circleci.com. Set it to your Server or Standalone install URL and reconnect.
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 Best Practices

  • Least-privilege user - Create the token under a user with only the project access CloudThinker needs
  • Approval for controls - Keep pipeline, rerun, rollback, and other write actions approval-gated
  • Token rotation - Rotate the Personal API Token regularly
  • Correct base URL - Use https://circleci.com for cloud, or your install URL for self-hosted Server or Standalone
  • Revoke when unused - Delete the token in CircleCI if you stop using the connection
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

Jenkins Connection

Build pipeline monitoring and job analysis

Approval

How approval-gated actions work