Linking code from Bitbucket Data Center

Looking for docs on Bitbucket Cloud? See this doc.

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

Examples

Sync individual repos

{
    "type": "bitbucket",
    "deploymentType": "server",
    "url": "https://mybitbucketdeployment.com",
    "repos": [
        "myProject/myRepo"
    ]
}

Sync all repos in a project

{
    "type": "bitbucket",
    "deploymentType": "server",
    "url": "https://mybitbucketdeployment.com",
    "projects": [
        "myProject"
    ]
}

Sync all repos

Requires a token to be set in order to access private repositories.

{
    "type": "bitbucket",
    "deploymentType": "server",
    "url": "https://mybitbucketdeployment.com",
    // Index all repos visible to the provided token
    "all": true
}

Exclude repos from syncing

{
    "type": "bitbucket",
    "deploymentType": "server",
    "url": "https://mybitbucketdeployment.com",
    // Include all repos in myProject...
    "projects": [
        "myProject"
    ],
    // ...except:
    "exclude": {
        // repos that are archived
        "archived": true,
        // repos that are forks
        "forks": true,
        // repos that match these glob patterns
        "repos": [
            "myProject/repo1",
            "myProject2/*"
        ]
    }
}

Authenticating with Bitbucket Data Center

In order to index private repositories, you’ll need to provide a HTTP Access Token. Tokens can be scoped to a user account, a project, or an individual repository. Only repositories visible to the token will be able to be indexed by Sourcebot.

If permission syncing is enabled, the token must have Repository Admin permissions so Sourcebot can read repository-level user permissions.

User account token

User account tokens grant access to all repositories the user can access. Because these are tied to a specific user account, you must also set the user field to that user’s username.

1. In Bitbucket Data Center, navigate to your profile → Manage account → HTTP access tokens and click Create token. Give it a name and grant it Project read and Repository read permissions.

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

{
    "type": "bitbucket",
    "deploymentType": "server",
    "url": "https://mybitbucketdeployment.com",
    "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": ["myProject/myRepo"],
    // "projects": ["myProject"],
    // "all": true
}

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

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

Project / repository token

Project and repository tokens are scoped to a specific project or repository.

1. In Bitbucket Data Center, navigate to the project or repository → Settings → HTTP access tokens and click Create token. Give it a name and grant it Repository read and Project read permissions.

2. Add the token property to your connection config:

{
    "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"
    },
    // At least one of the following is required to specify which repos to sync:
    "repos": ["myProject/myRepo"],
    // "projects": ["myProject"],
    // "all": true
}

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

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

Rate limiting

Bitbucket Data Center supports rate limiting to protect instance stability. Rate limiting applies to HTTP requests with basic or bearer authentication, which includes the REST API calls Sourcebot makes to sync repositories.

If rate limiting is enabled on your instance, Sourcebot may receive HTTP 429 (Too Many Requests) errors during sync. To prevent this, add a rate limiting exemption for the user (service account) whose token is used in your connection config.

To add an exemption:

1. In Bitbucket Data Center, go to Administration → Rate limiting → Exemptions tab.
2. Click Add exemption and find the service account user.
3. Select Allow unlimited requests (recommended) or set a custom token bucket size and refill rate appropriate for your sync volume.
4. Click Save.

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.

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
}