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

# Buildkite

> Read Buildkite organizations, pipelines, and builds, and trigger new builds

## At a glance

* **Availability**: Experimental ([how to enable](/cloud/integrations)).
* **Auth**: API key.
* **Connection**: The key comes from `BUILDKITE_API_TOKEN`.
* **Docs**: [https://buildkite.com/docs/apis/rest-api](https://buildkite.com/docs/apis/rest-api)

## Credentials

Set these per environment. See [Connect an integration](/cloud/integrations).

| Variable              | Required | Description                                                                                                                                                            |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BUILDKITE_API_TOKEN` | Yes      | Buildkite API access token with read\_pipelines and read\_builds scopes (write\_builds to trigger builds) [Docs](https://buildkite.com/docs/apis/managing-api-tokens). |

## Setup

1. **Sign in to Buildkite**: Use an existing organization or create one at [https://buildkite.com](https://buildkite.com) - free plans include API access. You need at least one pipeline to query builds.
2. **Create an API access token**: Go to [https://buildkite.com/user/api-access-tokens](https://buildkite.com/user/api-access-tokens), create a token scoped to your organization, and enable the read\_pipelines, read\_builds, and read\_organizations REST scopes. Add write\_builds if you want to trigger builds.
3. **Set the environment variable**: Add the token to your .env as BUILDKITE\_API\_TOKEN=...
4. **Verify access**: Run List Organizations, then List Pipelines with your organization slug.

* Requests authenticate with 'Authorization: Bearer \<token>' against [https://api.buildkite.com/v2](https://api.buildkite.com/v2)
* API tokens are scoped per organization and per REST scope - missing scopes return 403
* Pagination uses page and per\_page query parameters (max 100 per page)

Provider API reference: [https://buildkite.com/docs/apis/rest-api](https://buildkite.com/docs/apis/rest-api)

## Tools

| Tool               | Access | Description                                                        |
| ------------------ | ------ | ------------------------------------------------------------------ |
| List Organizations | Read   | List Buildkite organizations the token can access                  |
| List Pipelines     | Read   | List pipelines in an organization                                  |
| Get Pipeline       | Read   | Get a pipeline's configuration and build stats                     |
| List Builds        | Read   | List builds for a pipeline, optionally filtered by branch or state |
| Get Build          | Read   | Get a build including its jobs and their states                    |
| Create Build       | Write  | Trigger a new build on a pipeline                                  |

## Example prompts

* List the failed Buildkite builds on my main pipeline from today and summarize the commit messages.
* Trigger a new Buildkite build of HEAD on the main branch of my pipeline.