feat(bitbucket): add repository webhook triggers

[BillLeoutsakosvl346]

Summary

Depends on #6952.

Adds 19 automatically managed Bitbucket Cloud repository triggers covering:

• repository push, fork, update, commit-comment, and build-status events
• pull-request lifecycle, approval, changes-request, and comment events
• signed webhook creation/deletion with exact event matching
• generated Bitbucket trigger documentation and deployment integration metadata

Hook deployment uses the existing Bitbucket OAuth connection, workspace/repository selectors, refreshed credentials, and encoded repository paths. Each deployment creates one event-specific repository hook, verifies Bitbucket's raw-body HMAC-SHA256 signature, and removes the hook on undeploy. Bitbucket permits at most 50 webhooks per repository, and each deployed Sim trigger consumes one slot.

The follow-up hardening adds unique hook descriptions tied to the Sim webhook ID, 15-second management-request deadlines, candidate reconciliation/checkpoint reuse, safe rollback, blank-UUID rejection, and strict cleanup retries. Ambiguous URL/description matches are never broadly deleted.

Delivery idempotency uses Bitbucket's nonblank X-Request-UUID, copied into Sim's trusted provider-local idempotency header after untrusted incoming Sim headers are stripped. A controlled failed-delivery test produced automatic attempts 1, 2, and 3 with the same request UUID and identical payload; only X-Attempt-Number changed. Missing or blank request UUIDs retain the existing unique fallback, preferring a possible duplicate over silently suppressing a legitimate byte-identical event. If Bitbucket ever changes UUID stability across retries, duplicate delivery remains possible.

OAuth compatibility

Bitbucket OAuth consent now includes the webhook scope. Existing action-only credentials remain compatible with the prior seven action scopes; users deploying triggers with an older credential must reconnect/update access so the OAuth consumer grants Webhooks read/write. The OAuth consumer used for live validation was confirmed to have Webhooks read/write enabled. No database migration is required.

Deliberate omissions

• pullrequest:push, because Atlassian lists it without a documented payload schema
• Bitbucket Issues events, because they require the additional issue scope and are comparatively niche
• pipeline:span_created, because it is a low-level OpenTelemetry span payload
• stale repository events absent from the current catalog
• a generic all-events trigger

Type of Change

• Bug fix
• New feature
• Documentation
• Breaking change
• Other: ___________

Testing

Final review patch:

• 319 focused Bitbucket provider, trigger, and block tests
• compact request-UUID idempotency coverage for retries, distinct UUIDs, and missing/blank UUIDs
• provider registry assertion
• bun run scripts/generate-docs.ts
• bun run docs:check
• apps/sim type-check
• scoped Biome check
• git diff --check

Earlier branch validation covered Atlassian's HMAC vector, all 19 mappings/output contracts, lifecycle timeout/reconciliation/rollback/cleanup behavior, OAuth compatibility, trigger checks, lint, and the full test suite.

Live testing

Final browser/live validation verified 19 of 19 configured trigger events. The previously missing pullrequest:comment_updated event was reproduced successfully after editing a different, older comment with a clean interval: Bitbucket delivered it to the exact event-specific hook, ngrok observed HTTP 200 from Sim, and Sim ran BB-TR-16 with the expected event, hook/request metadata, comment object, commentId, and commentContent. A first edit to a newly created comment produced no provider request, consistent with Bitbucket-side edit suppression/coalescing; no Sim code change is required.

A separate controlled failed-delivery probe used an isolated temporary hook returning HTTP 500. Bitbucket sent three automatic attempts with the same X-Request-UUID and identical body while incrementing X-Attempt-Number from 1 through 3. The temporary hook was removed and the test repository metadata was restored afterward.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

N/A — no bespoke visual component was added.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 22, 2026 7:22pm

[cursor]

PR Summary

High Risk
Touches OAuth consent (new webhook scope), HMAC-verified webhook ingest, and automatic remote hook create/delete. Connector listing changes also gate deletion reconciliation, so bugs could drop events or incorrectly delete indexed documents.

Overview
Enables Bitbucket Cloud workflows to start from 19 repository and pull-request events. Sim now creates one signed, event-specific repository hook per trigger, verifies HMAC-SHA256 deliveries, and removes the hook on undeploy.

OAuth consent adds the webhook scope. Existing action-only credentials still work for tools; trigger deploy needs a reconnect so the consumer grants Webhooks read/write. Delivery idempotency uses Bitbucket’s X-Request-UUID. Hook management uses unique descriptions, 15s timeouts, candidate checkpoint reuse, and conservative rollback that never bulk-deletes ambiguous matches.

The knowledge connector is stricter: pagination envelopes and next URLs are validated, incomplete listings set listingTruncated, auth failures fail the sync, PR bodies prefer rendered description, and non-UTF-8 / unexpected redirects are skipped rather than indexed. Docs cover the new triggers and self-host OAuth scopes.

^{Reviewed by Cursor Bugbot for commit ea3a07e. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds 19 Bitbucket Cloud repository webhook triggers with signed delivery verification, event-specific subscription management, retry idempotency, OAuth scope support, generated documentation, and deployment metadata.

• Adds Bitbucket webhook deployment, reconciliation, rollback, and cleanup behavior.
• Registers trigger definitions and normalizes Bitbucket event payloads.
• Extends OAuth configuration with webhook permissions.
• Adds focused provider, trigger, connector, and registry coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/lib/webhooks/providers/bitbucket.ts	Implements signed Bitbucket hook lifecycle, reconciliation, rollback, cleanup, and delivery metadata handling; the previously flagged error normalization is fixed.
apps/sim/triggers/bitbucket/index.ts	Exports and registers the Bitbucket trigger catalog using valid absolute aliases; the previous relative-import violation is fixed.
apps/sim/triggers/bitbucket/utils.ts	Provides shared trigger configuration and event-payload normalization for the new Bitbucket triggers.
apps/sim/lib/oauth/oauth.ts	Extends Bitbucket OAuth authorization to support webhook management while preserving existing action scopes.
apps/sim/lib/webhooks/providers/bitbucket.test.ts	Covers signature verification, event matching, lifecycle timeouts, reconciliation, rollback, cleanup, and request-UUID idempotency.
apps/sim/triggers/registry.ts	Adds the Bitbucket trigger definitions to the application-wide trigger registry.
packages/deployment-config/src/integrations.json	Adds Bitbucket trigger deployment integration metadata.
apps/docs/content/docs/en/integrations/bitbucket.mdx	Documents the 19 new Bitbucket trigger configurations and output contracts.

Sequence Diagram

sequenceDiagram
  participant Sim as Sim deployment
  participant BB as Bitbucket API
  participant Hook as Bitbucket webhook
  participant WF as Workflow execution
  Sim->>BB: Create event-specific signed repository hook
  BB-->>Sim: Return hook UUID
  Hook->>Sim: Deliver event with raw-body HMAC and request UUID
  Sim->>Sim: Verify signature and exact event key
  Sim->>Sim: Apply provider-local idempotency key
  Sim->>WF: Start configured workflow
  Sim->>BB: Delete hook on undeploy

Loading

_{Reviews (3): Last reviewed commit: "fix(bitbucket): harden triggers and conn..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ea3a07e. Configure here.}