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. You can do this using an App Password or an Access Token
  • App Password
  • Access Token
Navigate to the app password creation page 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 PermissionsNext, provide your username + app password pair to Sourcebot:
  • Environment Variable
  • Secret
  1. Add the token and user (username associated with the app password you created) properties to your connection config:
{
    "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 ..
}
  1. Pass this environment variable each time you run Sourcebot:
docker run \
    -e BITBUCKET_TOKEN=<PAT> \
    /* 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 authentication. Only needed if token is an app password."
    },
    "token": {
      "description": "An authentication token.",
      "examples": [
        {
          "secret": "SECRET_KEY"
        }
      ],
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "secret": {
              "type": "string",
              "description": "The name of the secret that contains the token."
            }
          },
          "required": [
            "secret"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "env": {
              "type": "string",
              "description": "The name of the environment variable that contains the token. Only supported in declarative connection configs."
            }
          },
          "required": [
            "env"
          ],
          "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"
    },
    "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/repo1",
              "server_project/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
}
⌘I