BitBucket Cloud: API and git clone require different usernames with API tokens

[jpmorganuk]

BitBucket Cloud: API and git clone require different usernames with API tokens

Problem

BitBucket Cloud recently replaced App Passwords with API Tokens. With the new API tokens, the BitBucket REST API and git clone over HTTPS require different usernames:

• REST API (Basic auth): requires the user's email address (e.g. user+bitbucket@example.com)
• git clone (HTTPS credentials): requires the user's Atlassian username (e.g. userbitbucket)

SourceBot uses a single user field in the BitBucket connection config for both purposes:

• bitbucket.ts line 111 — API auth: Basic ${Buffer.from(${user}:${token}).toString('base64')}
• utils.ts line 185 — git clone URL: username: config.user ?? 'x-token-auth'

This means there is no valid value for user that works for both operations when using BitBucket Cloud API tokens.

Reproduction

1. Create a BitBucket Cloud API token (under Personal Settings → API Tokens)
2. Configure a BitBucket Cloud connection with "user": "your-email@example.com"
3. SourceBot discovers repos successfully (API auth works)
4. All git clone operations fail with Authentication failed (email doesn't work for git)
5. Change to "user": "your-atlassian-username"
6. API calls fail with Cannot read properties of undefined (reading 'values') (username doesn't work for API)
7. Git clone would succeed, but never gets attempted because step 6 fails first

Verified behaviour

Tested from inside the SourceBot container:

# API with email — works (HTTP 200)
curl -u user+tag@example.com:TOKEN https://api.bitbucket.org/2.0/repositories/WORKSPACE?pagelen=1

# API with Atlassian username — fails (HTTP 401)
curl -u atlassianuser:TOKEN https://api.bitbucket.org/2.0/repositories/WORKSPACE?pagelen=1

# git clone with Atlassian username — works
git clone https://atlassianuser:TOKEN@bitbucket.org/WORKSPACE/REPO.git

# git clone with email (URL-encoded) — fails (Authentication failed)
git clone https://user%2Btag%40example.com:TOKEN@bitbucket.org/WORKSPACE/REPO.git

Suggested fix

Add an optional gitUser field to the BitBucket connection config schema, used only for git clone credentials. Fall back to user if gitUser is not set.

Schema change (bitbucket.schema.ts):

"gitUser": {
  "type": "string",
  "description": "The username to use for git clone authentication. If not set, falls back to 'user'. Useful when the API and git require different usernames (e.g. BitBucket Cloud API tokens require email for API but Atlassian username for git)."
}

Code change (utils.ts line 185):

const username = config.gitUser ?? config.user ?? 'x-token-auth';

Type change (bitbucket.type.ts):

gitUser?: string;

This is fully backwards-compatible — existing configs without gitUser behave identically.

Config with proposed fix

{
  "type": "bitbucket",
  "deploymentType": "cloud",
  "user": "user+tag@example.com",
  "gitUser": "atlassianusername",
  "token": { "env": "BITBUCKET_TOKEN" },
  "workspaces": ["myworkspace"]
}

Environment

• SourceBot: latest Docker image (ghcr.io/sourcebot-dev/sourcebot:latest)
• BitBucket Cloud with API tokens (App Passwords deprecated)
• Private workspace with 208 repos