feat(integrations): add Bitbucket Cloud

[BillLeoutsakosvl346]

Summary

Adds a complete Bitbucket Cloud action integration with 30 OAuth-backed tools for repository/source inspection, pull request collaboration, and pipeline operations.

Includes:

• Bitbucket OAuth provider/configuration and self-hosted setup docs
• Bitbucket block with workspace/repository cascading selectors
• Structured, fail-closed request/response normalization, bounded raw reads, strict cursor binding, and safe retry behavior
• Generated tool metadata, integration catalog entries, icons, and action documentation

No triggers or webhooks are included.

Type of Change

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

Testing

• bunx vitest run app/api/tools/bitbucket hooks/selectors/providers/bitbucket blocks/blocks/bitbucket.test.ts tools/bitbucket — 323 tests passed
• bun run tool-metadata:check
• bun run check:tool-registry-boundary
• bun run apps/sim/scripts/check-canvas-sentences.ts --block=bitbucket — 30/30 operations
• bun run check:bare-icons
• bun run integration-catalog:check
• bun run docs:check
• bun run check:api-validation
• bun run type-check
• git diff --check

Reviewer focus:

• OAuth provider mapping and rotating-token persistence behavior
• Bitbucket-specific cursor/redirect validation and bounded raw-content handling
• Normalized nullable collection semantics and mutation input validation

Known follow-ups intentionally outside this PR:

• Shared multi-replica rotating-refresh coordination requires a separate provider-agnostic PR.
• Bitbucket's merge request-body type discriminator needs a disposable live-provider probe before adding an undocumented value.

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

Not applicable; no standalone visual workflow changes.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 20, 2026 2:11am

[cursor]

PR Summary

Medium Risk
Large new integration with OAuth and mutating APIs (merge/decline PRs, branch delete, pipeline trigger/stop), but mutations follow existing fail-closed credential and cursor-validation patterns rather than changing core auth.

Overview
Introduces a new Bitbucket Cloud action integration (OAuth only—no triggers or webhooks) so workflows can inspect repos and source, collaborate on pull requests, and run or diagnose pipelines.

The surface area is 30 registered tools (workspaces through pipeline step logs), a workflow block with operation-specific fields, cascading workspace/repository pickers, and server routes that authorize credentials, refresh tokens, and call Bitbucket with strict API cursor validation (host/path/workspace binding, no redirects) plus bounded JSON and raw reads.

OAuth is wired end-to-end: consumer config env vars, connector registration (basic-auth token exchange), self-hosted docs with required consumer permissions, connect-modal scope text keyed by provider, and catalog/docs/icons for the integration page.

Supporting tests cover block↔tool mapping, selector hooks, and repository/workspace API routes (auth order, malformed provider responses, cursor rejection).

^{Reviewed by Cursor Bugbot for commit f5cf56c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

Adds a complete Bitbucket Cloud OAuth integration for repository, source, pull-request, and pipeline workflows.

• Registers 30 Bitbucket tools and a corresponding workflow block with cascading workspace and repository selectors.
• Adds OAuth configuration, rotating-token support, bounded provider reads, redirect and cursor validation, normalized outputs, tests, generated metadata, catalog entries, icons, and documentation.

Confidence Score: 5/5

The PR appears safe to merge because no concrete blocking or independently actionable non-blocking defect was established in the changed paths.

The OAuth lifecycle, selector authorization, tool registry alignment, block parameter mapping, bounded reads, cursor validation, and normalized response handling form consistent end-to-end paths, and the investigated edge cases lacked a reachable contradictory provider or caller condition.

Important Files Changed

Filename	Overview
apps/sim/tools/bitbucket/utils.server.ts	Adds DNS-pinned, bounded, retry-aware reads and validated pull-request redirect resolution; no actionable defect was established.
apps/sim/tools/bitbucket/utils.ts	Centralizes request validation, cursor binding, response normalization, and bounded UTF-8 processing for the integration.
apps/sim/blocks/blocks/bitbucket.ts	Defines the 30-action block UI and maps editor values to registered tool parameters consistently.
apps/sim/lib/auth/connectors/providers.ts	Adds the Bitbucket connector authorization-code exchange and synthetic connector identity mapping.
apps/sim/lib/oauth/oauth.ts	Registers Bitbucket scopes and refresh-token configuration using Basic authentication and rotating-token persistence.
apps/sim/app/api/tools/bitbucket/workspaces/route.ts	Adds an authenticated, credential-authorized, bounded workspace selector endpoint with strict cursor validation.
apps/sim/app/api/tools/bitbucket/repositories/route.ts	Adds an authenticated repository selector bound to the selected workspace and validated provider pagination.
apps/sim/tools/registry.ts	Registers all new Bitbucket tool IDs referenced by the block.

Sequence Diagram

sequenceDiagram
  participant User as Workflow user
  participant Block as Bitbucket block
  participant Exec as Generic executor
  participant OAuth as OAuth credential service
  participant Tool as Bitbucket tool
  participant BB as Bitbucket Cloud

  User->>Block: Configure action and repository
  Block->>Exec: Tool ID and normalized parameters
  Exec->>OAuth: Resolve credential and refresh token if needed
  OAuth-->>Exec: Access token
  Exec->>Tool: Execute selected operation
  Tool->>BB: Authenticated API request
  BB-->>Tool: JSON, redirect, or bounded raw response
  Tool-->>Exec: Normalized output
  Exec-->>User: Workflow result

Loading

_{Reviews (1): Last reviewed commit: "feat(integrations): add Bitbucket Cloud" | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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