Bitbucket

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.

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
Self-hosted

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.

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.

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, API token authentication, and workspace token permissions. Atlassian documents the required scopes for build statuses and PR comments.

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 for your Bitbucket version.

Connect Bitbucket

You must have the Admin role in Vidoc.

Open the Bitbucket connection

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.

Fill in the connection form

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. Vidoc uses token-only authentication when this field is empty.
Git Username	The clone username from 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.

Test and save the connection

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.

Import repositories

In Import Bitbucket repositories, select the repositories to add to the current project. Click Import selected repositories.

Create the webhook in each repository

Open Integrations > Bitbucket. Open the actions menu of the Bitbucket account and select Configure webhook.
The Configure Bitbucket webhook dialog shows the Webhook URL, the Secret, and the Events. Use the copy buttons.
In Bitbucket, open the repository settings and create a webhook with the name Vidoc Security.
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

Open Integrations > Bitbucket.
Open the actions menu of the Bitbucket account and select Import repositories.
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.
Vidoc does not create the webhook. Make sure that each repository has the webhook from 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.

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 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.
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:

Open Integrations > Bitbucket.
Open the actions menu of the Bitbucket account and select Edit.
Paste the new token in PAT. If you keep the field empty, Vidoc keeps the saved token.
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.
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.
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.

Get started

Deployment

Integrations

Pull request reviews

Web app

CLI

API reference

Reference

Requirements

Prepare a token

Bitbucket Cloud

Bitbucket Data Center

Connect Bitbucket

Import more repositories later

Turn on PR reviews for repositories

Bitbucket specifics

Update credentials

Troubleshooting

​Requirements

​Prepare a token

​Bitbucket Cloud

​Bitbucket Data Center

​Connect Bitbucket

​Import more repositories later

​Turn on PR reviews for repositories

​Bitbucket specifics

​Update credentials

​Troubleshooting

Requirements

Prepare a token

Bitbucket Cloud

Bitbucket Data Center

Connect Bitbucket

Import more repositories later

Turn on PR reviews for repositories

Bitbucket specifics

Update credentials

Troubleshooting