> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bitbucket
> Connect Bitbucket Cloud or Bitbucket Data Center to Vidoc with an access token and a repository webhook.
Vidoc connects to Bitbucket with an access token. Vidoc does not create Bitbucket webhooks. You create one webhook in each repository by hand.
On Bitbucket, Vidoc can:
* Review each pull request (PR) and write a summary comment and inline comments.
* Resolve its own comment threads when a later scan shows that the issue is fixed.
* Show a build status, when status reporting is on.
* Collect 👍/👎 reactions on its inline comments (Bitbucket Data Center 7.21 and later only).
Vidoc does not read PR comments on Bitbucket. Commands, questions, "remember" requests, and replies to findings do not work. Use the Vidoc web app to change the status of a finding and to give feedback.
For a comparison with other platforms, refer to [Supported platforms](/supported-platforms).
## Requirements
Vidoc supports Bitbucket Cloud and Bitbucket Data Center. One Vidoc installation connects to one Bitbucket type only: Bitbucket Cloud or Bitbucket Data Center.
Vidoc Cloud does not support Bitbucket. The **Bitbucket** card on the **Integrations** page shows **Not available in this deployment**. To use Bitbucket, use a self-hosted installation. Refer to [Deployment options](/deployment-options).
Your operators configure the platform connection for the installation (see the installation guide that Vidoc provides). They select Bitbucket Cloud or Bitbucket Data Center for the installation.
When the operators complete this work, an admin connects Bitbucket in the web app with the steps below. You also need permission to create webhooks in the repositories to scan.
## Prepare a token
### Bitbucket Cloud
Use a scoped Atlassian API token or a workspace access token. App passwords were disabled on June 9, 2026. Replace an old app password before you connect. Refer to [Atlassian's app password notice](https://support.atlassian.com/bitbucket-cloud/docs/revoke-an-app-password/).
| Token | Permissions for Vidoc | **Username** | **Git Username** |
| ---------------------- | ------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
| Atlassian API token | `read:repository:bitbucket` and `read:pullrequest:bitbucket` | The Atlassian account email of the token owner | `x-bitbucket-api-token-auth`, or the owner's case-sensitive Bitbucket username |
| Workspace access token | Repositories: Read (`repository`) and Pull requests: Read (`pullrequest`) | Leave empty | Leave empty; Vidoc uses `x-token-auth` |
The token must cover every repository you import. The repository permission covers code access and build statuses. Bitbucket Cloud's pull request Read permission also permits creating, editing, and resolving comments. Vidoc does not create webhooks, so create them separately with an account that can manage repository webhooks.
For token creation and scope details, refer to [API token permissions](https://support.atlassian.com/bitbucket-cloud/docs/api-token-permissions/), [API token authentication](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/), and [workspace token permissions](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-token-permissions/). Atlassian documents the required scopes for [build statuses](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commit-statuses/) and [PR comments](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/).
### Bitbucket Data Center
Use an HTTP access token with Project read and Repository write permissions for repository access and PR actions. For a user token, set **Username** to the token owner's Bitbucket username; **Git Username** can stay empty. For a project token, leave **Username** empty and set **Git Username** to `x-token-auth`. Refer to [Atlassian's HTTP access token guide](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) for your Bitbucket version.
## Connect Bitbucket
You must have the **Admin** role in Vidoc.
In the web app, open the account menu and select **Integrations**. On the **Bitbucket** card, click **Connect**. If Bitbucket is already connected, click the card, then click **Add connection**.
In **Configure Bitbucket**, fill in these fields:
| Field | Value |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | Bitbucket Cloud: the workspace slug. Bitbucket Data Center: the project key. |
| **Username** | The API username from [Prepare a token](#prepare-a-token). Vidoc uses token-only authentication when this field is empty. |
| **Git Username** | The clone username from [Prepare a token](#prepare-a-token). Set it explicitly for an Atlassian API token so Vidoc does not reuse your email for Git. |
| **PAT** | The API token or access token. |
Click **Test Connection**. Vidoc checks whether it can list repositories with the Bitbucket API. This test does not verify Git clone access or PR comment permissions. **Save Bitbucket Connection** stays disabled until the test passes. Then click **Save Bitbucket Connection**.
In **Import Bitbucket repositories**, select the repositories to add to the current project. Click **Import selected repositories**.
1. Open **Integrations > Bitbucket**. Open the actions menu of the Bitbucket account and select **Configure webhook**.
2. The **Configure Bitbucket webhook** dialog shows the **Webhook URL**, the **Secret**, and the **Events**. Use the copy buttons.
3. In Bitbucket, open the repository settings and create a webhook with the name `Vidoc Security`.
4. Paste the URL and the secret. Turn on all the events that the dialog shows.
Repeat this step for each imported repository. If a repository has no webhook, Vidoc does not scan its PRs.
The dialog shows these events:
| Event in the dialog | Bitbucket Cloud event | Bitbucket Data Center event |
| ----------------------------------- | ----------------------------- | --------------------------- |
| Repository: Push | `repo:push` | `repo:refs_changed` |
| Pull request: Opened | `pullrequest:created` | `pr:opened` |
| Pull request: Source branch updated | `pullrequest:updated` | `pr:from_ref_updated` |
| Pull request: Modified | `pullrequest:updated` | `pr:modified` |
| Pull request: Merged | `pullrequest:fulfilled` | `pr:merged` |
| Pull request: Declined | `pullrequest:rejected` | `pr:declined` |
| Pull request: Comment added | `pullrequest:comment_created` | `pr:comment:added` |
| Pull request: Comment edited | `pullrequest:comment_updated` | `pr:comment:edited` |
| Pull request: Comment deleted | `pullrequest:comment_deleted` | `pr:comment:deleted` |
The copy button of the **Events** field copies the event names for your Bitbucket type.
### Import more repositories later
1. Open **Integrations > Bitbucket**.
2. Open the actions menu of the Bitbucket account and select **Import repositories**.
3. Create the webhook in each new repository.
## Turn on PR reviews for repositories
Open **Repositories** in the web app. Turn on the **PR reviews** toggle for each repository to scan. You must have the **Developer** role or higher.
When you turn on **PR reviews**:
* Vidoc indexes the default branch of the repository and then runs a first full scan of the default branch. Refer to [Scan types](/how-it-works#scan-types).
* Vidoc does not create the webhook. Make sure that each repository has the webhook from [Connect Bitbucket](#connect-bitbucket).
* Vidoc then reviews each new PR and each update to a PR.
The **PR comments** toggle is in the actions menu of each repository. When it is off, Vidoc still scans PRs, but it does not write to Bitbucket. For all repository controls, refer to [Repositories](/web-app/repositories).
## Bitbucket specifics
| Topic | Behavior on Bitbucket |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scan triggers | A scan starts when a PR opens, when you push new commits, and when you change the title, description, or labels. Each new scan stops the running scan. |
| Scan again | Push a new commit, or click **Rerun scan** on the PR in the [Pull requests](/web-app/pull-requests) page of the web app (**Developer** role or higher). Commands are not available. |
| Commands, questions, "remember" requests | Not supported. Vidoc does not read PR comments on Bitbucket. |
| Replies on findings | Not supported. Change the status of a finding in the web app. Refer to [Feedback](/pull-requests/feedback#feedback-on-bitbucket). |
| Reactions | Bitbucket Data Center 7.21 and later: Vidoc collects 👍 and 👎 on its inline comments. Bitbucket Cloud: not collected. |
| Inline comments | Bitbucket Data Center: Vidoc writes inline comments only on added lines. A finding on another line shows only in the summary comment. |
| Build status | When status reporting is on, Vidoc shows a build status on the head commit. |
| Comment formatting | Vidoc converts its comments to Bitbucket markdown. Collapsed sections show expanded. Alert blocks can show as normal quotes or bold labels. |
| SCM usernames | Bitbucket Cloud: enter your Bitbucket nickname. Bitbucket Data Center: enter your Bitbucket username. Bitbucket Cloud does not give user emails to Vidoc. |
## Update credentials
Replace the token before it expires, or after you rotate it in Bitbucket:
1. Open **Integrations > Bitbucket**.
2. Open the actions menu of the Bitbucket account and select **Edit**.
3. Paste the new token in **PAT**. If you keep the field empty, Vidoc keeps the saved token.
4. Click **Test Connection**, then click **Save Bitbucket Connection**.
## Troubleshooting
| Symptom | Cause | Fix |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Test Connection** fails: `Bitbucket credentials are invalid or do not have access to this workspace` | The token is incorrect, expired, or has no access to the workspace (Cloud) or project (Data Center). Or **Username** does not match the token type. | Check the token, scopes, and **Username** against [Prepare a token](#prepare-a-token). |
| **Test Connection** fails: `Bitbucket workspace was not found or is not accessible` | The workspace slug (Cloud) or project key (Data Center) is incorrect. | Enter the correct value. |
| Save fails: `Bitbucket Data Center requires Username or Git Username for clone access` | **Username** and **Git Username** are both empty. | Enter **Git Username** (or **Username**). Test and save again. |
| **Test Connection** passes, but cloning fails | The Git username is incorrect for the token type, or the token cannot read the repository. | For an Atlassian API token, set **Git Username** to `x-bitbucket-api-token-auth`. Check repository access and token scopes. |
| PRs get no Vidoc scan. Bitbucket shows no webhook request | The repository has no Vidoc webhook, or the webhook does not have all the events. | Create the webhook with the URL, secret, and events from **Configure webhook**. |
| The webhook request returns 401 `Invalid webhook signature` | The secret in the Bitbucket webhook is incorrect. | Copy the secret from **Configure webhook** again and paste it in the Bitbucket webhook. |
| The webhook request returns 400 `Missing x-hub-signature header` | The Bitbucket webhook has no secret. | Add the secret from **Configure webhook** to the webhook. |
| Imports, scans, or comments fail after a token change in Bitbucket | The saved token is revoked or expired. | Save the new token. Refer to [Update credentials](#update-credentials). |
| A PR has no Vidoc comment | **PR reviews** or **PR comments** is off for the repository, the webhook is missing, or the scan still runs. | On the **Repositories** page, make sure that **PR reviews** and **PR comments** are on. Examine the webhook. Wait some minutes. |
| The summary comment shows "Currently scanning commit ..." for more than 30 minutes | The scan failed. | Push a new commit, or click **Rerun scan** on the PR in the web app. |
| A finding is in the summary but has no inline comment | On Bitbucket Data Center, the finding is not on an added line. | Use the location link in the summary comment. |
| The Bitbucket card shows **Not available in this deployment** | Bitbucket is not turned on for your installation. | Vidoc Cloud: contact Vidoc. Self-hosted: ask your operators. |