> ## Documentation Index
> Fetch the complete documentation index at: https://sourcebot-whoisthey-pin-citation-commit-sha.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Linking code from Bitbucket Cloud

<Note>
  Looking for docs on Bitbucket Data Center? See [this doc](/docs/connections/bitbucket-data-center).
</Note>

If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first.

## Examples

<AccordionGroup>
  <Accordion title="Sync individual repos">
    ```json theme={null}
    {
        "type": "bitbucket",
        "deploymentType": "cloud",
        "repos": [
            "myWorkspace/myRepo"
        ]
    }
    ```
  </Accordion>

  <Accordion title="Sync all repos in a workspace">
    ```json theme={null}
    {
        "type": "bitbucket",
        "deploymentType": "cloud",
        "workspaces": [
          "myWorkspace"
        ]
    }
    ```
  </Accordion>

  <Accordion title="Sync all repos in a project">
    ```json theme={null}
    {
        "type": "bitbucket",
        "deploymentType": "cloud",
        "projects": [
            "myProject"
        ]
    }
    ```
  </Accordion>

  <Accordion title="Exclude repos from syncing">
    ```json theme={null}
    {
        "type": "bitbucket",
        "deploymentType": "cloud",
        // Include all repos in my-workspace...
        "workspaces": [
            "myWorkspace"
        ],
        // ...except:
        "exclude": {
            // repos that are archived
            "archived": true,
            // repos that are forks
            "forks": true,
            // repos that match these glob patterns
            "repos": [
                "myWorkspace/repo1",
                "myWorkspace2/*"
            ]
        }
    }
    ```
  </Accordion>
</AccordionGroup>

## 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 `API Token`, `Access Token`, or `App Password`.

<Tabs>
  <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 theme={null}
    {
        "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"
        },
        // At least one of the following is required to specify which repos to sync:
        "repos": ["myWorkspace/myRepo"],
        // "workspaces": ["myWorkspace"],
        // "projects": ["myProject"]
    }
    ```

    6. Pass this environment variable each time you run Sourcebot:

    ```bash theme={null}
    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.

    1. Add the `token` property to your connection config:

    ```json theme={null}
    {
        "type": "bitbucket",
        "deploymentType": "cloud",
        "token": {
            // note: this env var can be named anything. It
            // doesn't need to be `BITBUCKET_TOKEN`.
            "env": "BITBUCKET_TOKEN"
        },
        // At least one of the following is required to specify which repos to sync:
        "repos": ["myWorkspace/myRepo"],
        // "workspaces": ["myWorkspace"],
        // "projects": ["myProject"]
    }
    ```

    2. Pass this environment variable each time you run Sourcebot:

    ```bash theme={null}
    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)

    <img src="https://mintcdn.com/sourcebot-whoisthey-pin-citation-commit-sha/957auaeBl6dzRmSg/images/bitbucket_app_password_perms.png?fit=max&auto=format&n=957auaeBl6dzRmSg&q=85&s=073cca4db9969543639a9079c0987e0f" alt="Bitbucket App Password Permissions" width="1358" height="854" data-path="images/bitbucket_app_password_perms.png" />

    1. Add the `user` (your Bitbucket username) and `token` properties to your connection config:

    ```json theme={null}
    {
        "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"
        },
        // At least one of the following is required to specify which repos to sync:
        "repos": ["myWorkspace/myRepo"],
        // "workspaces": ["myWorkspace"],
        // "projects": ["myProject"]
    }
    ```

    2. Pass this environment variable each time you run Sourcebot:

    ```bash theme={null}
    docker run \
        -e BITBUCKET_TOKEN=<APP_PASSWORD> \
        /* additional args */ \
        ghcr.io/sourcebot-dev/sourcebot:latest
    ```
  </Tab>
</Tabs>

## Schema reference

<Accordion title="Reference">
  [schemas/v3/bitbucket.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/bitbucket.json)

  ```json theme={null}
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "BitbucketConnectionConfig",
    "properties": {
      "type": {
        "const": "bitbucket",
        "description": "Bitbucket configuration"
      },
      "user": {
        "type": "string",
        "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.",
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "env": {
                "type": "string",
                "description": "The name of the environment variable that contains the token."
              }
            },
            "required": [
              "env"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "googleCloudSecret": {
                "type": "string",
                "description": "The resource name of a Google Cloud secret. Must be in the format `projects/<project-id>/secrets/<secret-name>/versions/<version-id>`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets"
              }
            },
            "required": [
              "googleCloudSecret"
            ],
            "additionalProperties": false
          }
        ]
      },
      "url": {
        "type": "string",
        "format": "url",
        "default": "https://api.bitbucket.org/2.0",
        "description": "Bitbucket URL",
        "examples": [
          "https://bitbucket.example.com"
        ],
        "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$"
      },
      "deploymentType": {
        "type": "string",
        "enum": [
          "cloud",
          "server"
        ],
        "default": "cloud",
        "description": "The type of Bitbucket deployment"
      },
      "all": {
        "type": "boolean",
        "default": false,
        "description": "Sync all repositories visible to the provided `token` (if any) in the Bitbucket Server instance. This option is ignored if `deploymentType` is `cloud`."
      },
      "workspaces": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "List of workspaces to sync. Ignored if deploymentType is server."
      },
      "projects": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "List of projects to sync"
      },
      "repos": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "List of repos to sync"
      },
      "exclude": {
        "type": "object",
        "properties": {
          "archived": {
            "type": "boolean",
            "default": false,
            "description": "Exclude archived repositories from syncing."
          },
          "forks": {
            "type": "boolean",
            "default": false,
            "description": "Exclude forked repositories from syncing."
          },
          "repos": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "cloud_workspace/PROJECT_KEY/repo1",
                "SERVER_PROJECT_KEY/repo2"
              ]
            ],
            "description": "List of specific repos to exclude from syncing."
          }
        },
        "additionalProperties": false
      },
      "revisions": {
        "type": "object",
        "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.",
        "properties": {
          "branches": {
            "type": "array",
            "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "main",
                "release/*"
              ],
              [
                "**"
              ]
            ],
            "default": []
          },
          "tags": {
            "type": "array",
            "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "latest",
                "v2.*.*"
              ],
              [
                "**"
              ]
            ],
            "default": []
          }
        },
        "additionalProperties": false
      },
      "enforcePermissions": {
        "type": "boolean",
        "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing"
      },
      "enforcePermissionsForPublicRepos": {
        "type": "boolean",
        "default": false,
        "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing"
      }
    },
    "required": [
      "type"
    ],
    "if": {
      "properties": {
        "deploymentType": {
          "const": "server"
        }
      }
    },
    "then": {
      "required": [
        "url"
      ]
    },
    "additionalProperties": false
  }
  ```
</Accordion>