Skip to main content

Bitbucket API Token Authentication (Breaking Change)

Version: 3.0.0 Date: 2026-05-07

Goal: Support Bitbucket Cloud's new API token authentication, replacing deprecated App passwords.

Solution: Migrated all Bitbucket API calls to Basic auth (email:API_TOKEN) and Git clone URLs to x-bitbucket-api-token-auth:API_TOKEN. Added a dedicated email field to Bitbucket source configuration.

Impact: Clients upgrading to this version must update their Bitbucket source configuration:

  • Create a Bitbucket API token (scopes: account read, repositories read, webhooks).
  • Re-save the Bitbucket source in Tower with the account email and the new API token.
  • Existing sources using App passwords will no longer work.

Features:

  • New email field on Bitbucket sources (required, validated in schema and DTO)
  • API calls use Basic base64(email:token) authorization
  • Git clone uses x-bitbucket-api-token-auth:token in URL
  • buildBasicAuth utility centralises Basic auth header construction

Implementation Details:

  • HookActionBase now carries a generic authorizationHeader: string — WebhookCapacityService is auth-agnostic
  • Each provider builds its own Authorization header in its factory
  • Removed catchError → of([]) in getHooks so auth failures surface in init report
  • Fixed isInitOk vacuous-truth bug: empty init report no longer counts as success

Files Modified:

  • src/protocol/source/auth.util.ts - New buildBasicAuth utility
  • src/protocol/source/source.types.ts - authorizationHeader replaces authToken in HookActionBase
  • src/protocol/source/bitbucket/bitbucket.types.ts - Added email field
  • src/protocol/source/bitbucket/bitbucket.service.ts - Basic auth for all API calls
  • src/protocol/source/gitlab/gitlab.service.ts - Bearer header in factory
  • src/protocol/source/github/github.service.ts - Bearer header in factory
  • src/protocol/capacities/webhook-capacity/webhook-capacity.service.ts - Generic auth header
  • src/app.service.ts - Bitbucket-specific clone URL
  • src/config.dto.ts - email field + require_tld: false
  • src/core/configuration/config.schema.ts - Joi email validation
  • src/core/data/data.service.ts - Fixed isInitOk
  • src/app.controller.ts - Discover uses source.email
  • ui/src/pages/workflows/sources.types.ts - email on TypedSource
  • ui/src/pages/workflows/context.tsx - Reducer passes email for Bitbucket
  • ui/src/pages/workflows/stepForms/StepInitForm.tsx - Email field