Buildkite

Prerequisites

Before setting up the Buildkite integration, ensure you have:

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

Required Token Scopes

Your Buildkite API token must include 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

Setting Up Buildkite Integration

Step 1: Create Buildkite API Access Token

Recommended: Use a Service Account

For production environments, we strongly recommend creating a dedicated service account:

• Benefits: Prevents issues when team members leave, easier token management, better audit trails
• Example: Create a user like buildkite-integration@yourcompany.com

To create an API Access Token:

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)

Step 2: Access Gitar Integrations Page

1. Navigate to your Gitar organization settings
2. Go to the Integrations section
3. Look for the Buildkite integration
4. Click "Connect" to begin the setup process

Step 3: Configure Buildkite Connection

When you click the Buildkite "Connect" button, you'll be prompted to enter:

Buildkite API Token

• Enter your Buildkite API Access Token
• The token will be securely stored and encrypted
• Gitar will verify the token by making a test API call to Buildkite

Step 4: Complete Connection

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

How It Works

Once connected, Gitar will:

• Monitor CI Status: Track build statuses for your pipelines
• Analyze Failures: Automatically analyze failed builds and identify root causes
• Create Fixes: Generate pull requests with potential fixes for CI failures
• Access Build Data: Retrieve build logs, artifacts, and environment information for analysis

Features

Build Monitoring

• Real-time tracking of Buildkite build statuses
• Integration with GitHub/GitLab status checks
• Automatic detection of failed builds across all pipelines

Failure Analysis

• Automated analysis of build logs using the Buildkite API
• Identification of common failure patterns
• Root cause analysis with suggested fixes
• Access to job environment variables for context

Build Data Access

• Download and analyze build artifacts
• Access detailed build logs for troubleshooting
• Retrieve job-specific environment variables
• Integration with test suite results

Troubleshooting

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
• Only grant the minimum required scopes for your use case