Skip to main content

Bitbucket API Token Authentication

Overview​

Bitbucket Cloud deprecated App passwords in favour of API tokens. Tower now uses Basic auth (email:API_TOKEN) for all Bitbucket API calls and x-bitbucket-api-token-auth:token for Git clone URLs.

This is a breaking change: existing Bitbucket sources using App passwords must be reconfigured.

How it works​

  1. The user provides an account email and a Bitbucket API token (scopes: account read, repositories read, webhooks).
  2. All Bitbucket API calls (webhook management, commit status, project discovery) use Basic base64(email:token).
  3. Git clone URLs use the token-specific username x-bitbucket-api-token-auth with the token as the password.

Migration​

  • Create a Bitbucket API token.
  • Re-save the Bitbucket source in Tower with the account email and the new API token.
  • Existing App password sources will no longer authenticate.

Key files​

  • src/protocol/source/auth.util.ts — buildBasicAuth utility
  • src/protocol/source/bitbucket/bitbucket.service.ts — Basic auth for all Bitbucket calls
  • src/protocol/source/bitbucket/bitbucket.types.ts — email field on BitbucketSource
  • src/config.dto.ts — email field in CreateSourceDto
  • src/core/configuration/config.schema.ts — Joi email validation
  • ui/src/pages/workflows/stepForms/StepInitForm.tsx — Email field and pre-fill

Technical decisions​

  • HookActionBase now carries a generic authorizationHeader: string instead of authToken, making WebhookCapacityService auth-agnostic. Each provider builds its own header.
  • catchError → of([]) was removed from getHooks so auth failures surface in the init report.
  • Fixed isInitOk vacuous-truth bug: an empty init report no longer counts as success.

Known issues​

  • Bitbucket and FTP still require a manual username/email field (unlike GitHub/GitLab which auto-discover the username).