Skip to main content

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.

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

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

​
Setup

1

Create a Buildkite API Access Token

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.
  1. Log into your Buildkite account
  2. Go to 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)
2

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
3

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.Buildkite integration formBuildkite 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

​
Troubleshooting

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
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
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

​
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