Skip to main content
Connect CircleCI so CloudThinker agents can read pipeline status, pull build and test logs to find why a run failed, spot flaky tests, and validate your .circleci/config.yml. The connection uses a CircleCI personal API token, so agents reach exactly the projects the token’s user can see.

​
Prerequisites

  • A CircleCI account that can see the organization and projects you want agents to investigate.
  • At least one project that account follows. Agents discover projects from the followed list. To follow one, sign in to CircleCI as the token’s user, open Projects, and click Follow Project next to each repository.
  • For flaky tests and job test results: your jobs must upload JUnit results with store_test_results. Without it, CircleCI has no test data to return.
  • To let agents start or rerun pipelines: the same account needs permission to trigger pipelines on those projects.
  • For a self-hosted CircleCI Server: the server must be reachable from CloudThinker over HTTPS. See Reaching private services.

​
Setup

1

Create a personal API token

In CircleCI, open User Settings → Personal API Tokens (app.circleci.com/settings/user/tokens) and click Create New Token. Name it cloudthinker.Copy the token right away. CircleCI shows it only once.
2

Add the connection

Open More → Workspace settings → Connections, stay on the Builtin Connections tab, and select CircleCI. Fill in:
  • CIRCLECI_TOKEN: the token you just created.
  • CIRCLECI_BASE_URL: leave it as https://circleci.com for CircleCI cloud. Change it only for a self-hosted CircleCI Server install.
Click Connect.Success state: the dialog closes and the connection shows Connected.
3

Confirm the token works

Run the prompt in Verify the connection. CloudThinker doesn’t check the token with CircleCI when you connect, so a Connected status alone doesn’t prove the token is valid.

​
Connection details

There’s no organization or project ID to enter. Agents resolve them from the token’s followed projects.

​
Required permissions

A personal API token has the same access as the CircleCI user who created it. That user’s project access is the ceiling on what agents can read or change. Evaluation tests are CircleCI’s prompt-template tests: the agent runs them as a pipeline on CircleCI.
Create the token under a dedicated CircleCI user that only belongs to the projects you want investigated. That user needs membership in your GitHub or Bitbucket organization, so a VCS machine user is the usual pattern. Check whether it counts as a user on your CircleCI plan. Write actions still go through Approvals, so the token sets the ceiling and Approvals decides each action.

​
Agent capabilities

Before any write, the agent tells you what will happen (for example, “starts a pipeline on gh/acme/api branch main”) and shows the exact inputs. A rollback also lists the current and target versions and asks you to confirm the target. Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself. To be asked every time, choose Manual as your Approval mode so a person approves every change. Once CloudThinker turns on Rule enforcement for your workspace, an Ask first Rule can narrow that to this connection alone.

​
Verify the connection

Expect each followed project by slug (such as gh/acme/api) with its latest pipeline status. A project you expected but don’t see isn’t followed by the token’s user.

​
Example prompts

​
Troubleshooting

The token is missing, expired, or revoked. Create a new personal API token and update the CIRCLECI_TOKEN field on the connection.
The token’s user can read the project but can’t trigger pipelines on it. Create the token under a user with trigger permission on that project, then update the connection.
The token’s user follows no projects. Follow at least one project in CircleCI, then ask again.
The jobs don’t upload test results. Add a store_test_results step that points at your JUnit XML output, let a few pipelines run, then ask again.
Project slugs need a VCS prefix: gh/<org>/<repo> for GitHub or bb/<org>/<repo> for Bitbucket. Ask the agent to list your followed projects and use the slug from that list.
Usage data needs the organization UUID, which no CircleCI API call returns. Copy it from Organization Settings → Overview → Organization ID in CircleCI and paste it into the chat. The usage API is paid-plan only and covers up to 32 days per request.
CIRCLECI_BASE_URL is still https://circleci.com, or it includes a path. Set it to your CircleCI Server host only, such as https://circleci.example.com.

​
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.
  • Use a dedicated user: CircleCI personal tokens have no scopes of their own, so the token user’s project membership is the only way to limit reach.
  • Keep controls approval-gated: a pipeline run bills compute and can deploy. Leave these actions behind Approval mode rather than auto-approving them.

Buildkite

Pipeline health, failed-build triage, and approval-gated retries.

Approvals

How CloudThinker decides which actions need a person to approve.