Buildkite

Connect Buildkite so agents can track pipeline health, triage failed builds from logs, and retry or unblock jobs through your Approvals

Connect Buildkite so CloudThinker agents can measure pipeline health, find why a build failed from its logs and annotations, and check agent capacity. The connection uses a Buildkite API access token, and the scopes you grant it are the hard limit on what agents can do.

Prerequisites

• A Buildkite account with access to the organization you want agents to monitor.
• Permission to create an API access token for that organization.

Setup

1. Create an API access token

   In Buildkite, go to Personal Settings → API Access Tokens → New API Access Token (buildkite.com/user/api-access-tokens/new) and set:

   • Description: cloudthinker
   • Organization access: the organization CloudThinker should reach
   • REST API scopes: read_organizations, read_pipelines, read_builds, read_build_logs, read_artifacts, read_agents, read_clusters, and read_user. Add write_builds only if you want agents to retry, unblock, rebuild, or cancel.

   Copy the token right away. Buildkite shows it only once.

2. Add the connection

   Open More → Workspace settings → Connections, stay on the Builtin Connections tab, and select Buildkite. Paste the token into BUILDKITE_API_TOKEN and click Connect.

   Success state: the dialog closes and the connection shows Connected.

3. Confirm the token works

   Run the prompt in Verify the connection. Buildkite accepts the connection even with a bad token and only rejects it when an agent makes its first call, so a Connected status alone doesn’t prove the token is valid.

Connection details

Field	Description
BUILDKITE_API_TOKEN	Buildkite API access token. Its scopes decide which operations succeed

There’s no organization slug to enter. Agents resolve it from the token. CloudThinker sends the token to Buildkite’s hosted MCP server at https://mcp.buildkite.com/direct, which passes it to the Buildkite REST API. Buildkite runs that server, not CloudThinker.

Required permissions

Scope	Required	Enables
read_organizations	Yes	Resolving the organization the token can reach
read_pipelines	Yes	Pipeline inventory and details
read_builds	Yes	Builds, jobs, annotations, and failure summaries
read_build_logs	Yes	Reading, searching, and tailing job logs
read_artifacts	Yes	Build and job artifacts
read_agents	Yes	Agent connection state and capacity
read_clusters	Yes	Clusters and cluster queues
read_user	Yes	Looking up the token’s own user
write_builds	No	Retry a job, unblock a job, rebuild, and cancel

Leave write_builds off for a monitoring-only connection. Agents keep every read, and Buildkite itself refuses any change, so you aren’t relying on approvals alone.

Agent capabilities

Capability	What agents can do
Discovery	List pipelines, recent builds, agents, and clusters in the organization
Pipeline health	Report pass rate, failure streak, and builds stuck longer than a threshold you name in the prompt, such as “stuck for more than 30 minutes”
Failed-build triage	Cross-reference Buildkite’s failure summary with job logs, annotations, and failed tests
Logs and artifacts	Read, search, and tail a job’s log; list and fetch build and job artifacts
Capacity	Show agent connection state, clusters, and cluster queues
Build controls	Retry a job, unblock a job, rebuild a build, cancel a build. Each goes through your Approvals

A build waiting on a manual block step reports passed in the Buildkite API. Agents check for the gate, name the block step, and leave the build out of the pass rate, so a held deploy never shows up as a green pipeline. Before unblocking, the agent quotes the block step’s label and the build’s annotations so you know which gate you’re releasing.

Agents can’t create or edit pipelines, clusters, queues, or schedules, and they don’t read job environment variables. Buildkite Test Engine data isn’t available through this connection.

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

List my Buildkite pipelines and show the latest build status for each

Expect each pipeline by slug with its newest build state. A 401 here means the token is invalid even though the connection shows Connected.

Example prompts

Which Buildkite pipelines are failing right now, and how long is each failure streak?
Build 42 of the web pipeline failed. Pull the logs and annotations and tell me the cause
Show Buildkite agent capacity and any builds stuck for more than an hour

Troubleshooting

Connected, but every request returns 401

The token is invalid, expired, or revoked. Create a new API access token and update BUILDKITE_API_TOKEN on the connection.

403 on reads

The token is missing a read scope. Check it against Required permissions and edit the token’s scopes in Buildkite. You don’t need a new token.

Retry, unblock, rebuild, or cancel fails with a permission error

The token doesn’t have write_builds. Add the scope in Buildkite, or keep the connection read-only and run the action in Buildkite yourself.

The gate state shows as unknown

The check for a manual block step failed, usually because of a rate limit. The agent treats the build as unfinished and leaves it out of the pass rate. Unknown never means ungated. Ask again in a minute.

404 on a pipeline that exists

A pipeline name was used where Buildkite expects the slug. Ask the agent to list your pipelines and use the slug from that list.

429 rate limited

The request covered too many pipelines or builds. Scope the question to one pipeline, or ask for fewer recent builds.

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.

• Scope the token, not just the approval: Buildkite enforces token scopes. A token without write_builds can’t change CI state at all.
• Treat unblock as a release: a block step is usually a deploy gate someone added on purpose. Approve an unblock only after reading the label the agent quotes.

Related

CircleCI

Pipeline status, failure logs, flaky tests, and reruns that wait for approval.

Approvals

How CloudThinker decides which actions need a person to approve.