Linking code from Bitbucket Cloud

Looking for docs on Bitbucket Data Center? See this doc.

If you’re not familiar with Sourcebot connections, please read that overview first.

Examples

Sync individual repos

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

Sync all repos in a workspace

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

Sync all repos in a project

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

Exclude repos from syncing

{
    "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.

API Token

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": "[e-mail]",
    "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:

docker run \
    -e BITBUCKET_TOKEN=<API_TOKEN> \
    /* additional args */ \
    docker.sourcebot.dev/sourcebot-dev/sourcebot:latest

Access Token

Create an access token for the desired scope (repo, project, or workspace). Visit the official Bitbucket Cloud docs for more info.

1. Add the token property to your connection config:

{
    "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:

docker run \
    -e BITBUCKET_TOKEN=<ACCESS_TOKEN> \
    /* additional args */ \
    docker.sourcebot.dev/sourcebot-dev/sourcebot:latest

App Password

App Passwords are deprecated. Atlassian recommends migrating to API tokens. Learn more

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)

1. Add the user (your Bitbucket username) and token 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"
    },
    // 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:

docker run \
    -e BITBUCKET_TOKEN=<APP_PASSWORD> \
    /* additional args */ \
    docker.sourcebot.dev/sourcebot-dev/sourcebot:latest

Schema reference

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
    },
    "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
}