> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buildkite AI Connector

> Connect Rootly AI to Buildkite through read-only OAuth so investigations can inspect pipelines, builds, jobs, logs, artifacts, agents, and Test Engine results.

## Overview

The Buildkite AI connector gives Rootly AI current CI/CD evidence during an investigation. Rootly AI can inspect pipelines and builds, trace a failed build to its jobs and logs, check artifacts and annotations, and correlate Test Engine failures with an incident.

The connection uses Buildkite's hosted, read-only Model Context Protocol (MCP) server. You authorize Rootly from Buildkite through OAuth; you don't create or paste an API token. Rootly always connects to Buildkite's dedicated read-only endpoint and can't trigger, retry, cancel, or modify pipelines and builds.

<Note>
  Buildkite also offers remote MCP endpoints with write access and API token pass-through. The Rootly AI connector doesn't use or accept either option. See [Buildkite's MCP server overview](https://buildkite.com/docs/apis/mcp-server#types-of-mcp-servers-remote-mcp-server) for the differences between its MCP server types.
</Note>

***

## Before You Start

You'll need:

* **A Buildkite user account** with access to each organization and pipeline Rootly AI should investigate.
* **Permission to authorize OAuth applications** in Buildkite.
* **Permission in Rootly to manage AI connectors.**

Rootly AI inherits the authorizing user's Buildkite access. Choose an account that can see the pipelines, clusters, and Test Engine suites relevant to your incidents.

***

## Connect Buildkite

<Steps>
  <Step title="Open the Buildkite AI connector">
    In Rootly, go to **AI & Agents → Connectors** and select **Connect** on the **Buildkite** card.
  </Step>

  <Step title="Authorize Rootly in Buildkite">
    Rootly opens Buildkite's authorization screen. Sign in if prompted, review the read-only access, and approve the connection.

    If the authorization screen doesn't open, allow popups for your Rootly domain and try again.
  </Step>

  <Step title="Confirm the connection">
    Rootly verifies the hosted MCP server and its required pipeline, build, job, and log tools. After the check succeeds, the card displays **Connected**.
  </Step>
</Steps>

If you reconnect, Rootly keeps the working connection until the replacement authorization and tool check both succeed.

***

## What Rootly AI Can Read

The reviewed Buildkite tool set covers these investigation surfaces:

| Surface                  | What Rootly AI can inspect                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Pipelines and builds** | Pipelines, builds, failure summaries, annotations, schedules, dynamic step uploads, and build completion state           |
| **Jobs and logs**        | Job state and details, environment data exposed by Buildkite, complete or partial logs, log searches, and live log tails |
| **Artifacts**            | Artifact lists and individual artifacts for a build or job                                                               |
| **Agents and clusters**  | Connected agents, clusters, and cluster queues                                                                           |
| **Test Engine**          | Test suites, runs, tests, failed executions, and tests associated with a build                                           |
| **Identity**             | The Buildkite user and organizations represented by the OAuth grant                                                      |

Buildkite's read-only endpoint exposes only tools whose required scope begins with `read_`, plus tools that require no scope. Rootly also pins the reviewed tool names, so an upstream tool added later doesn't become available until Rootly reviews it.

<Warning>
  Job environment data can contain sensitive values if your pipeline exposes them through Buildkite. Restrict the authorizing user's access to the organizations and pipelines Rootly AI needs.
</Warning>

## Investigation Examples

Try questions that start broad and then narrow to the failing job or test:

* *"Which Buildkite build first failed before this incident, and what changed from the last passing build?"*
* *"Summarize the failed jobs in the latest build. Show only the log lines that support the diagnosis."*
* *"Did the build promise a failure before the job finished? Check the final job result and any later logs."*
* *"Are the same tests failing across recent Test Engine runs, or is this failure new?"*
* *"Did an agent or queue problem delay this build?"*
* *"Find artifacts and annotations from the failed build that could explain the deployment regression."*

Buildkite can report a build as `failing` while a job is still `running` when the job has declared a promised failure. Rootly AI can begin investigating that signal, then wait for the terminal result and check for additional logs, artifacts, or test results.

***

## Access and Data Handling

* **No personal API token:** You don't create or paste a Buildkite API access token. Rootly stores the OAuth access and refresh credentials encrypted so it can use and refresh the connection.
* **Read-only endpoint:** Rootly fixes the connection to `https://mcp.buildkite.com/mcp/readonly`.
* **Permission-scoped:** Rootly AI sees only data available to the Buildkite user who authorized the connection.
* **Reviewed tools:** Rootly limits the connector to its pinned, read-only tool set.
* **Investigation-time queries:** Rootly queries Buildkite when the investigation needs CI/CD evidence.
* **Redacted session history:** Raw Buildkite tool results are available to the active investigation but aren't persisted in the AI session transcript.
* **Quality traces:** As with other Rootly AI tool calls, connector results can appear in retained large language model (LLM) traces used for quality monitoring. See [Data Privacy for Rootly AI](/ai/data-privacy-for-rootly-ai) for the retention boundary.

Buildkite documents OAuth access tokens as valid for 12 hours and refresh tokens as valid for seven days. Rootly refreshes the connection when possible. Reconnect if the authorization can no longer be refreshed.

Requests through Buildkite's remote MCP server use a rate-limit quota separate from the organization's REST API quota. See [Buildkite's remote MCP rate limits](https://buildkite.com/docs/apis/mcp-server/remote/rate-limits).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Buildkite authorization screen doesn't open" icon="arrow-up-right-from-square">
    Allow popups for your Rootly domain, then select **Connect** again. If a popup is already open, switch to it and complete or cancel the pending authorization.
  </Accordion>

  <Accordion title="Buildkite denies the OAuth request" icon="key">
    Confirm you're signed in to the intended Buildkite account and that your organization allows you to authorize OAuth applications. Ask a Buildkite organization administrator if authorization is restricted.
  </Accordion>

  <Accordion title="The connector is connected but a pipeline is missing" icon="lock">
    The authorizing Buildkite user can't access that pipeline or organization. Grant the user the required Buildkite access, then reconnect the AI connector so the authorization represents the intended account.
  </Accordion>

  <Accordion title="Rootly AI can't find artifacts, schedules, agents, or Test Engine results" icon="magnifying-glass">
    An empty result can be valid. Confirm that the selected build produced artifacts, the pipeline has schedules, agents are connected, or Test Engine is configured for the pipeline. Rootly AI can only inspect data that exists in Buildkite and remains within its retention window.
  </Accordion>

  <Accordion title="A dynamic step upload can't be found" icon="clock-rotate-left">
    Buildkite retains dynamic pipeline uploads for a limited period. Try a newer build or inspect the pipeline definition in the source repository.
  </Accordion>

  <Accordion title="Buildkite queries fail after the connector worked previously" icon="rotate-right">
    The OAuth authorization may have expired, been revoked, or lost access after a Buildkite role change. Open the Buildkite card and reconnect. A failed reconnect leaves the previous connection unchanged.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can Rootly AI trigger, retry, or cancel a Buildkite build?" icon="lock">
    No. Rootly uses Buildkite's dedicated read-only MCP endpoint and exposes only a reviewed read-only tool set.
  </Accordion>

  <Accordion title="Can I connect with a Buildkite API token?" icon="key">
    No. The Buildkite AI connector supports OAuth only. You authorize the connection in Buildkite without creating or pasting an API token.
  </Accordion>

  <Accordion title="Can Rootly AI read multiple Buildkite organizations?" icon="building">
    Yes, when the authorizing Buildkite user can access them. Rootly AI inherits that user's organization and pipeline permissions.
  </Accordion>

  <Accordion title="How do I limit which Buildkite data Rootly AI sees?" icon="filter">
    Limit the authorizing user's Buildkite access. Use a user whose organization, pipeline, cluster, and Test Engine permissions match the scope Rootly AI should investigate.
  </Accordion>
</AccordionGroup>

***

## Related Pages

<CardGroup cols={3}>
  <Card title="Connectors Overview" icon="sparkles" href="/ai/connectors/overview">
    See every AI connector and how Rootly AI combines their evidence.
  </Card>

  <Card title="Semaphore" icon="code" href="/ai/connectors/semaphore">
    Connect another CI/CD source for pipelines, jobs, and logs.
  </Card>

  <Card title="Data Privacy for Rootly AI" icon="shield" href="/ai/data-privacy-for-rootly-ai">
    Review Rootly AI's data access, retention, and training controls.
  </Card>
</CardGroup>