feat(bitbucket): add gitUser field to support API token auth on Bitbucket Cloud

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Skip calling `getCommitHashForRefName` for empty repositories to avoid noisy debug log output. [#914](https://github.com/sourcebot-dev/sourcebot/pull/914)
 
+### Added
+- Added optional `gitUser` field to the Bitbucket connection config to support Bitbucket Cloud API tokens, which require an email address for the REST API but an Atlassian username for git clone. [#918](https://github.com/sourcebot-dev/sourcebot/pull/918)
+
 ## [4.11.4] - 2026-02-20
 
 ### Fixed

docs/docs/connections/bitbucket-cloud.mdx

@@ -4,8 +4,6 @@ sidebarTitle: Bitbucket Cloud
 icon: Bitbucket
 ---
 
-import BitbucketToken from '/snippets/bitbucket-token.mdx';
-import BitbucketAppPassword from '/snippets/bitbucket-app-password.mdx';
 import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx'
 
 <Note>
@@ -78,25 +76,107 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview),
 
 ## Authenticating with Bitbucket Cloud
 
-In order to index private repositories, you'll need to provide authentication credentials via a [token](/docs/configuration/config-file#tokens). You can do this using an `App Password` or an `Access Token`
+In order to index private repositories, you'll need to provide authentication credentials via a [token](/docs/configuration/config-file#tokens). You can do this using an `API Token`, `Access Token`, or `App Password`.
 
 <Tabs>
-    <Tab title="App Password">
-      Navigate to the [app password creation page](https://bitbucket.org/account/settings/app-passwords/) and create an app password. Ensure that it has the proper permissions for the scope
-      of info you want to fetch (i.e. workspace, project, and/or repo level) 
-      ![Bitbucket App Password Permissions](/images/bitbucket_app_password_perms.png)
-
-      Next, provide your username + app password pair to Sourcebot:
-
-      <BitbucketAppPassword />
+    <Tab title="API Token">
+      1. Navigate to [Personal Settings → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and click **Create API token with scopes**. Give the token a name and set an expiry date.
+
+      2. Select **Bitbucket** as the app.
+
+      3. Select the following scopes:
+         - `read:repository:bitbucket` — View your repositories
+         - `read:workspace:bitbucket` — View your workspaces
+
+      4. Click **Create token** and copy the token value.
+
+      5. Add the `user` (your account email), `gitUser` (your Bitbucket username), and `token` to your connection config. [Learn why both are needed](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/)
+
+      ```json
+      {
+          "type": "bitbucket",
+          "deploymentType": "cloud",
+          "user": "you@example.com",
+          "gitUser": "myusername",
+          "token": {
+              // note: this env var can be named anything. It
+              // doesn't need to be `BITBUCKET_TOKEN`.
+              "env": "BITBUCKET_TOKEN"
+          }
+          // .. rest of config ..
+      }
+      ```
+
+      6. Pass this environment variable each time you run Sourcebot:
+
+      ```bash
+      docker run \
+          -e BITBUCKET_TOKEN=<API_TOKEN> \
+          /* additional args */ \
+          ghcr.io/sourcebot-dev/sourcebot:latest
+      ```
     </Tab>
     <Tab title="Access Token">
       Create an access token for the desired scope (repo, project, or workspace). Visit the official [Bitbucket Cloud docs](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
       for more info.
 
-      Next, provide the access token to Sourcebot:
+      1. Add the `token` property to your connection config:
+
+      ```json
+      {
+          "type": "bitbucket",
+          "deploymentType": "cloud",
+          "token": {
+              // note: this env var can be named anything. It
+              // doesn't need to be `BITBUCKET_TOKEN`.
+              "env": "BITBUCKET_TOKEN"
+          }
+          // .. rest of config ..
+      }
+      ```
+
+      2. Pass this environment variable each time you run Sourcebot:
+
+      ```bash
+      docker run \
+          -e BITBUCKET_TOKEN=<ACCESS_TOKEN> \
+          /* additional args */ \
+          ghcr.io/sourcebot-dev/sourcebot:latest
+      ```
+    </Tab>
+    <Tab title="App Password">
+      <Warning>
+        App Passwords are deprecated. Atlassian recommends migrating to API tokens. [Learn more](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation)
+      </Warning>
+
+      Navigate to the [app password creation page](https://bitbucket.org/account/settings/app-passwords/) and create an app password. Ensure that it has the proper permissions for the scope
+      of info you want to fetch (i.e. workspace, project, and/or repo level)
+      ![Bitbucket App Password Permissions](/images/bitbucket_app_password_perms.png)
 
-      <BitbucketToken />
+      1. Add the `user` (your Bitbucket username) and `token` properties to your connection config:
+
+      ```json
+      {
+          "type": "bitbucket",
+          "deploymentType": "cloud",
+          "user": "myusername",
+          "token": {
+              // note: this env var can be named anything. It
+              // doesn't need to be `BITBUCKET_TOKEN`.
+              "env": "BITBUCKET_TOKEN"
+          }
+          // .. rest of config ..
+      }
+      ```
+
+      2. Pass this environment variable each time you run Sourcebot:
+
+      ```bash
+      docker run \
+          -e BITBUCKET_TOKEN=<APP_PASSWORD> \
+          /* additional args */ \
+          ghcr.io/sourcebot-dev/sourcebot:latest
+      ```
     </Tab>
 </Tabs>
 

docs/docs/connections/bitbucket-data-center.mdx

@@ -4,8 +4,6 @@ sidebarTitle: Bitbucket Data Center
 icon: Bitbucket
 ---
 
-import BitbucketToken from '/snippets/bitbucket-token.mdx';
-import BitbucketAppPassword from '/snippets/bitbucket-app-password.mdx';
 import BitbucketSchema from '/snippets/schemas/v3/bitbucket.schema.mdx'
 
 <Note>
@@ -75,9 +73,30 @@ In order to index private repositories, you'll need to provide an access token t
 Create an access token for the desired scope (repo, project, or workspace). Visit the official [Bitbucket Data Center docs](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html)
 for more info.
 
-Next, provide the access token to Sourcebot:
-
-<BitbucketToken />
+1. Add the `token` property to your connection config:
+
+```json
+{
+    "type": "bitbucket",
+    "deploymentType": "server",
+    "url": "https://mybitbucketdeployment.com",
+    "token": {
+        // note: this env var can be named anything. It
+        // doesn't need to be `BITBUCKET_TOKEN`.
+        "env": "BITBUCKET_TOKEN"
+    }
+    // .. rest of config ..
+}
+```
+
+2. Pass this environment variable each time you run Sourcebot:
+
+```bash
+docker run \
+    -e BITBUCKET_TOKEN=<ACCESS_TOKEN> \
+    /* additional args */ \
+    ghcr.io/sourcebot-dev/sourcebot:latest
+```
 
 ## Troubleshooting
 If you're seeing errors like `TypeError: fetch failed` when fetching repo info, it may be that Sourcebot is refusing to connect to your self-hosted Bitbucket instance due to unrecognized SSL certs. Try setting the `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable or providing Sourcebot your certs through the `NODE_EXTRA_CA_CERTS` environment variable.

docs/snippets/schemas/v3/bitbucket.schema.mdx

@@ -11,7 +11,11 @@
     },
     "user": {
       "type": "string",
-      "description": "The username to use for authentication. Only needed if token is an app password."
+      "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+    },
+    "gitUser": {
+      "type": "string",
+      "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
     },
     "token": {
       "description": "An authentication token.",

docs/snippets/schemas/v3/connection.schema.mdx

@@ -688,7 +688,11 @@
         },
         "user": {
           "type": "string",
-          "description": "The username to use for authentication. Only needed if token is an app password."
+          "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+        },
+        "gitUser": {
+          "type": "string",
+          "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
         },
         "token": {
           "description": "An authentication token.",

docs/snippets/schemas/v3/index.schema.mdx

@@ -1103,7 +1103,11 @@
                 },
                 "user": {
                   "type": "string",
-                  "description": "The username to use for authentication. Only needed if token is an app password."
+                  "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+                },
+                "gitUser": {
+                  "type": "string",
+                  "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
                 },
                 "token": {
                   "anyOf": [

packages/backend/src/utils.ts

@@ -182,7 +182,7 @@ export const getAuthCredentialsForRepo = async (repo: RepoWithConnections, logge
             const config = connection.config as unknown as BitbucketConnectionConfig;
             if (config.token) {
                 const token = await getTokenFromConfig(config.token);
-                const username = config.user ?? 'x-token-auth';
+                const username = config.gitUser ?? config.user ?? 'x-token-auth';
                 return {
                     hostUrl: config.url,
                     token,

packages/schemas/src/v3/bitbucket.schema.ts

@@ -10,7 +10,11 @@ const schema = {
     },
     "user": {
       "type": "string",
-      "description": "The username to use for authentication. Only needed if token is an app password."
+      "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+    },
+    "gitUser": {
+      "type": "string",
+      "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
     },
     "token": {
       "description": "An authentication token.",

packages/schemas/src/v3/bitbucket.type.ts

@@ -6,9 +6,13 @@ export interface BitbucketConnectionConfig {
    */
   type: "bitbucket";
   /**
-   * The username to use for authentication. Only needed if token is an app password.
+   * The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address.
    */
   user?: string;
+  /**
+   * The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username
+   */
+  gitUser?: string;
   /**
    * An authentication token.
    */

packages/schemas/src/v3/connection.schema.ts

@@ -687,7 +687,11 @@ const schema = {
         },
         "user": {
           "type": "string",
-          "description": "The username to use for authentication. Only needed if token is an app password."
+          "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+        },
+        "gitUser": {
+          "type": "string",
+          "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
         },
         "token": {
           "description": "An authentication token.",

packages/schemas/src/v3/connection.type.ts

@@ -257,9 +257,13 @@ export interface BitbucketConnectionConfig {
    */
   type: "bitbucket";
   /**
-   * The username to use for authentication. Only needed if token is an app password.
+   * The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address.
    */
   user?: string;
+  /**
+   * The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username
+   */
+  gitUser?: string;
   /**
    * An authentication token.
    */

packages/schemas/src/v3/index.schema.ts

@@ -1102,7 +1102,11 @@ const schema = {
                 },
                 "user": {
                   "type": "string",
-                  "description": "The username to use for authentication. Only needed if token is an app password."
+                  "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+                },
+                "gitUser": {
+                  "type": "string",
+                  "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
                 },
                 "token": {
                   "anyOf": [

packages/schemas/src/v3/index.type.ts

@@ -455,9 +455,13 @@ export interface BitbucketConnectionConfig {
    */
   type: "bitbucket";
   /**
-   * The username to use for authentication. Only needed if token is an app password.
+   * The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address.
    */
   user?: string;
+  /**
+   * The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username
+   */
+  gitUser?: string;
   /**
    * An authentication token.
    */

schemas/v3/bitbucket.json

@@ -9,7 +9,11 @@
         },
         "user": {
             "type": "string",
-            "description": "The username to use for authentication. Only needed if token is an app password."
+            "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address."
+        },
+        "gitUser": {
+            "type": "string",
+            "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username"
         },
         "token": {
             "$ref": "./shared.json#/definitions/Token",