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

# Buildkite

> Connect Buildkite for enhanced failure analysis and automatic fixes

export const ThemeImage = ({src, alt}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

Gitar automatically integrates with **GitHub Actions** and **GitLab Pipelines** -- no setup required. If you use Buildkite as an external CI platform, connect it here so Gitar can read build logs, analyze failures, and push fixes.

## Prerequisites

* Access to your Buildkite account
* A Buildkite API Access Token with the required scopes
* Admin permissions in your organization (recommended for service accounts)

## Required Token Scopes

<Warning>
  Your Buildkite API token must include **all** of the following scopes:

  * `read_teams` -- Access team information
  * `read_artifacts` -- Download build artifacts
  * `read_builds` -- View build information and status
  * `read_job_env` -- Access job environment variables
  * `read_build_logs` -- Read build logs for analysis
  * `read_organizations` -- View organization details
  * `read_pipelines` -- Access pipeline configurations
  * `read_user` -- Verify user account information
  * `read_suites` -- Access test suite information
</Warning>

## Setup

<Steps>
  <Step title="Create a Buildkite API Access Token">
    <Note>
      **Recommended: Use a Service Account.** Create a dedicated account like `buildkite-integration@yourcompany.com` to prevent issues when team members leave and provide better audit trails.
    </Note>

    1. Log into your Buildkite account
    2. Go to [API Access Tokens](https://buildkite.com/user/api-access-tokens)
    3. Click **"New API Access Token"**
    4. Name it **"Gitar Integration"**
    5. Select all the required scopes listed above
    6. Copy the token immediately (you won't be able to see it again)
  </Step>

  <Step title="Access Gitar Integrations">
    1. Navigate to your Gitar organization settings
    2. Go to the **Integrations** section
    3. Find the **Buildkite** integration
    4. Click **"Connect"** to begin the setup process
  </Step>

  <Step title="Configure and Connect">
    Enter your Buildkite API Access Token. The token will be securely stored and encrypted. Gitar verifies the token by making a test API call to Buildkite.

    <ThemeImage src="/assets/images/conn-buildkite-dark.png" alt="Buildkite integration form" />

    1. Fill in the required API token field
    2. Click **"Connect Buildkite"** to establish the connection
    3. If successful, the integration status will show as connected
    4. If the connection fails, verify your token is valid and has all required scopes
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed">
    If your connection fails, verify:

    * Buildkite API token is correct and valid
    * Token includes all required scopes listed above
    * Token has not expired
    * You have sufficient permissions in Buildkite
    * Buildkite service is accessible
  </Accordion>

  <Accordion title="Invalid Token or Insufficient Permissions">
    If you receive permission errors:

    * Check that your token includes all 9 required scopes
    * Verify you're using an API Access Token (not a different token type)
    * Ensure your user account has access to the organization
    * Try creating a new token with the correct scopes
  </Accordion>

  <Accordion title="Missing Build Data">
    If Gitar isn't detecting your builds:

    * Ensure your repositories are connected to both your Git provider and Buildkite
    * Verify your Buildkite pipelines are properly configured
    * Check that status checks are enabled for your Git provider
    * Confirm your token has `read_builds` and `read_pipelines` scopes
  </Accordion>

  <Accordion title="Scope-Related Issues">
    If certain features aren't working:

    * **Can't access logs**: Verify `read_build_logs` scope
    * **Missing artifacts**: Check `read_artifacts` scope
    * **No environment data**: Ensure `read_job_env` scope
    * **Team information missing**: Confirm `read_teams` scope
  </Accordion>
</AccordionGroup>

## Security Notes

* API tokens are encrypted and securely stored using AWS Secrets Manager
* Tokens can be revoked at any time from your Buildkite account settings
* We recommend rotating tokens regularly for enhanced security
* Use service accounts for production environments to avoid disruption when team members leave
* Only grant the minimum required scopes for your use case