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 land in the project's No release bucket, ready to be assigned to a release 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)

Project-scoped or org-scoped? A project-scoped key routes every build to its project. An org-scoped key must name the project in each payload with project_key (see How It Works).

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://lathe.studio/api/webhooks/bitbucket
    • Triggers: Select "Pipeline events"
    • Active: Check this box
  5. Add the header:
    • Authorization: Bearer <your-api-key>

3. Test the Integration

  1. Trigger a pipeline in Bitbucket
  2. Go to your project's Builds page in Lathe Studio
  3. You should see the build in the No release bucket
  4. Assign it to a release when ready

Authentication Methods#

Method 1: Connection Webhook Token (Recommended)

If you added a Bitbucket connection under Project Settings → Integrations, use the generated webhook URL — it already contains your connection's unique ?token=... parameter and is bound to that project. When a webhook secret is configured on the connection, requests must also carry a valid X-Hub-Signature HMAC signature.

Method 2: API Key

Include the API key in the Authorization header:

Authorization: Bearer ptk_xxxxxxxxxxxxxxxx

Benefits:

  • Rate limiting per key
  • Usage tracking
  • Scoped permissions

With an org-scoped API key, the payload must include project_key — the project's UUID or project code:

{
  "project_key": "MOB",
  "repository": { "full_name": "org/repo" },
  "pipeline": { ... }
}

Without project_key the event is refused with 400 and nothing is created — there is no default or inferred project.

How It Works#

  1. Pipeline Completes → Bitbucket sends the pipeline event to /api/webhooks/bitbucket
  2. Authentication → The webhook token (or API key) identifies your organization and project
  3. Project Resolution → Connection token / project-scoped key → that project. Org-scoped key → the project_key field in the payload (project UUID or project code, looked up inside your organization).
  4. Build Created → The build goes through the standard intake path: it always lands in the project's No release bucket (duplicate pipeline runs of the same build are deduplicated, and a build whose name already exists is suffixed "name (2)" rather than refused). A build.created.v1 webhook event fires once per created build.
  5. Assignment → Assign the build to a release from the Builds/Releases page when ready.

To report CI test results, create an API key with results:submit and run lathe report <file> --project <code>. The CLI reads JUnit XML, TestNG XML (testng-results.xml), NUnit 3 XML, xUnit.net v2 XML, and Cucumber JSON. It detects each file's format; use --format to specify one. Cypress, Playwright, Postman (Newman), pytest, and Appium-based suites already produce JUnit XML. The direct results-ingest API accepts JSON payloads, not raw files.

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. Org-scoped key: verify the payload includes project_key and that the code matches a project in your organization (a 400 names project_key; a 404 means the project wasn't found)
  4. Check that the pipeline event is being sent

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://lathe.studio/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"
  }'

With an org-scoped key add "project_key": "MOB" (project UUID or code). release_id is optional — without it the build lands in the project's No release bucket. See POST /builds in the API reference for the full schema.

Response:

  • 201 Created - Build created (check name — a suffix is added if the bucket already has that name)
  • 400 Bad Request - Org-scoped key without project_key
  • 404 Not Found - project_key or release_id names nothing in your organization
  • 401 Unauthorized - Invalid API key
  • 429 Too Many Requests - Rate limit exceeded

Breaking change (2026-09-24): builds are created immediately in the project's No release bucket. The Build Queue and repo-URL project matching are gone — there is no 202 Accepted / queued state, and repo_url is stored as metadata only (it no longer selects a project).

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
  • Connection-based webhooks verify an X-Hub-Signature HMAC signature when a webhook secret is configured
← All DocsSettings →