Skip to main content
Looking for docs on Bitbucket Data Center? See this doc.
If you’re not familiar with Sourcebot connections, please read that overview first.

​
Examples

{
    "type": "bitbucket",
    "deploymentType": "cloud",
    "repos": [
        "myWorkspace/myRepo"
    ]
}

{
    "type": "bitbucket",
    "deploymentType": "cloud",
    "workspaces": [
      "myWorkspace"
    ]
}

{
    "type": "bitbucket",
    "deploymentType": "cloud",
    "projects": [
        "myProject"
    ]
}

{
    "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/*"
        ]
    }
}

​
Authenticating with Bitbucket Cloud

In order to index private repositories, you’ll need to provide authentication credentials via a token. You can do this using an API Token, Access Token, or App Password.
  1. Navigate to Personal Settings → 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 
{
    "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 ..
}
  1. Pass this environment variable each time you run Sourcebot:
docker run \
    -e BITBUCKET_TOKEN=<API_TOKEN> \
    /* additional args */ \
    ghcr.io/sourcebot-dev/sourcebot:latest

​
Schema reference

schemas/v3/bitbucket.json
{
  "$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
    }
  },
  "required": [
    "type"
  ],
  "if": {
    "properties": {
      "deploymentType": {
        "const": "server"
      }
    }
  },
  "then": {
    "required": [
      "url"
    ]
  },
  "additionalProperties": false
}