All Docs
Bitbucket Pipelines Integration

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:

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
← All DocsSettings →