# Bitbucket Pipelines Integration

## Overview

This integration allows Bitbucket Pipelines to automatically notify Lathe Studio when builds complete, creating builds that can be assigned to releases for testing.

## Setup

### 1. Create an API Key

1. Go to **Settings > Organization > API Keys**  
2. Click **Create API Key**  
3. Give it a name (e.g., "Bitbucket Pipelines")  
4. Select scopes:  
   - `builds:read` - View builds  
   - `builds:create` - Create new builds  
5. Copy the generated key (shown only once)

### 2. Configure Bitbucket Webhook

1. In Bitbucket, go to your repository  
2. Navigate to **Repository settings > Webhooks**  
3. Click **Add webhook**  
4. Configure:  
   - **Title**: Lathe Studio  
   - **URL**: `https://your-app.com/api/webhooks/bitbucket`  
   - **Triggers**: Select "Pipeline events"  
   - **Active**: Check this box  
5. Optionally add headers:  
   - `Authorization: Bearer <your-api-key>` (if using API key auth)  
   - `X-Pt-Org-Id: <your-org-id>` (if using org ID auth)

### 3. Test the Integration

1. Trigger a pipeline in Bitbucket  
2. Go to **Releases** page in Lathe Studio  
3. You should see the build in the **Build Queue** section  
4. Assign it to a release

## Authentication Methods

### Method 1: API Key (Recommended)

Include the API key in the Authorization header:

```
Authorization: Bearer pt_live_xxxxxxxxxxxxxxxx
```

Benefits:

- Rate limiting per key
- Usage tracking
- Scoped permissions

### Method 2: Organization ID

Include your organization ID in a custom header:

```
X-Pt-Org-Id: your-org-uuid
```

Note: This method has basic rate limiting and is less secure. Use API keys for production.

## How It Works

1. **Pipeline Completes** → Bitbucket sends webhook to `/api/webhooks/bitbucket`  
2. **Authentication** → Webhook verifies API key or org ID  
3. **Project Matching** → System tries to match repo URL to a project  
4. **Queue or Create**:  
   - If project + active release found → Build created directly  
   - If project found but no release → Queued for release assignment  
   - If no project match → Queued for project + release assignment  
5. **Assignment** → User assigns queued builds via Releases page

## Build Queue UI

The Build Queue appears on the Releases page when there are pending builds:

- Shows build name, source (Bitbucket/GitHub/etc), project, commit/branch  
- **Assign to Release**: Select an active release for the project  
- **Select Project**: Navigate to projects if project not auto-detected  
- **Reject**: Remove build from queue (no build created)

## Troubleshooting

### Builds not appearing

1. Check webhook delivery in Bitbucket (Repository settings > Webhooks > View requests)  
2. Verify API key is not expired or revoked  
3. Check that the pipeline event is being sent

### Wrong project assigned

The system matches by:

1. Repository URL (exact match)  
2. Repository name (partial match)

You can manually assign to the correct project from the queue.

### Rate limiting

API keys are limited to 60 requests per minute by default. Contact support to increase limits.

## API Reference

### Direct API Usage

You can also create builds directly via the REST API:

```bash
curl -X POST https://your-app.com/api/v1/builds \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{\
    "name": "Build #123",\
    "build_number": "123",\
    "commit_sha": "abc123...",\
    "branch": "main",\
    "repo_url": "https://bitbucket.org/org/repo"\
  }'
```

Response:

- `201 Created` - Build created with release  
- `202 Accepted` - Build queued for manual assignment  
- `401 Unauthorized` - Invalid API key  
- `429 Too Many Requests` - Rate limit exceeded

## Security

- API keys are hashed using SHA-256 before storage
- Only the first 12 characters are stored for identification
- Keys can be revoked at any time
- Webhook signatures (HMAC) support planned for future releases