Bitbucket Cloud Integration

Connect Codeveira to Bitbucket Cloud using an app password. Webhook payloads are signed with HMAC-SHA256 so every push is verified before triggering a code review.

Prerequisites

Before you start, make sure you have the following:

A Bitbucket Cloud account at bitbucket.org
Access to the workspace that contains the repository you want to connect
Admin access to your Codeveira installation

This guide covers Bitbucket Cloud (bitbucket.org) only. For self-hosted Bitbucket Server or Data Center, see the separate guide.

How Codeveira integrates with Bitbucket Cloud

Codeveira connects to Bitbucket Cloud through a read-only API connection and an event-driven webhook — opening a code review automatically on every push. Developers push code normally; Codeveira handles everything else.

Read-only API access

The app password you create in Step 1 authenticates Codeveira against the Bitbucket Cloud REST API v2. All calls are read-only — Codeveira never creates pull requests, modifies repositories or writes to your Bitbucket workspace. The app password is used to:

Fetch commit metadata: author, message, timestamp and parent commit hashes
Download the unified diff for each commit (GET /2.0/repositories/{workspace}/{slug}/diff/{spec})
Retrieve repository information and list commits on a branch
Read raw file content for syntax-highlighted diff display

App passwords in Bitbucket Cloud are account-scoped, not repository-scoped. If you want tighter isolation, create a dedicated Bitbucket Cloud account for Codeveira and grant that account Repository: Read access to only the repositories it needs to monitor.

Automatic review creation via webhooks

The webhook you configure in Step 3 delivers repo:push events from Bitbucket Cloud to /webhooks/bitbucket. Codeveira verifies the payload against the BITBUCKET_WEBHOOK_SECRET using HMAC-SHA256, then:

Reads the list of new commits from the push event
Groups consecutive commits by the same author into a single code review
Creates the review, fetches the full diff via the API
Notifies assigned reviewers by email
Triggers the AI reviewer bot (if configured) to post inline comments

The BITBUCKET_WEBHOOK_SECRET variable in .env is the shared secret between Bitbucket Cloud and Codeveira. If this variable is not set, Codeveira accepts all payloads without signature verification — always set it in production.

Create an app password

Codeveira authenticates to Bitbucket Cloud using an app password. Generate one in your Bitbucket account settings:

Click your avatar in the top-right corner and go to Personal settings
Open the App passwords tab
Click Create app password
Enter a label such as Codeveira
Under Permissions, enable Repositories: Read — nothing else is needed
Click Create and copy the generated password — it is shown only once

When adding the repository in Codeveira, the token field expects the format username:app_password. Use your Bitbucket username here, not your email address.

App passwords in Bitbucket Cloud cannot be scoped to a single repository — they apply to your entire account. If you prefer isolation, create a dedicated Bitbucket account for Codeveira and grant that account read access to only the repositories you need.

Add the repository in Codeveira

With the app password ready, register the repository inside Codeveira:

Go to Repositories → New Repository
Click Bitbucket to select the platform
Fill in the following fields:

Name — display name for the repository in Codeveira
Workspace/Repo path — e.g. myworkspace/myrepo
Token — your credentials in username:app_password format

The workspace slug is visible in your Bitbucket URL: bitbucket.org/{workspace}/{repo}. Use the slug, not the display name, in the path field.

Click Save. Codeveira will immediately attempt to fetch recent commits to verify the connection.

Configure the webhook

Add a webhook to your Bitbucket repository so Codeveira is notified on every push:

In your Bitbucket repository go to Repository settings → Webhooks → Add webhook
Set Title to Codeveira
Set URL to: https://codeveira.yourdomain.com/webhooks/bitbucket
Set Secret to the value of BITBUCKET_WEBHOOK_SECRET from your .env
Under Triggers, expand the Repository section and enable Push (repo:push)
Click Save

Bitbucket Cloud signs webhook payloads with HMAC-SHA256 using the secret you configured. Codeveira verifies the X-Hub-Signature header on every incoming request — payloads with an invalid or missing signature are rejected.

To confirm the webhook is working, push a commit to the repository and check Repository settings → Webhooks → View recent deliveries in Bitbucket. A successful delivery shows HTTP 200.

Troubleshooting

"Invalid credentials" when saving the repository

Codeveira received a 401 response from the Bitbucket API. The most common cause is entering an email address instead of a username in the token field. The expected format is username:app_password where username is your Bitbucket account username (visible in your profile URL at bitbucket.org/{username}), not your email.

"Repository not found" error

The workspace slug or repository slug in the Workspace/Repo path field is incorrect. Copy both slugs directly from the Bitbucket repository URL (bitbucket.org/{workspace}/{repo}) to avoid typos. Note that slugs are case-sensitive.

Webhook not triggering after a push

Check the delivery log in Bitbucket: Repository settings → Webhooks → View recent deliveries. If no delivery appears, confirm that the Push trigger is enabled and the webhook is marked as active. If deliveries appear but return a non-200 status, check your Codeveira application logs for details on why the request was rejected.

Next: LDAP / Active Directory → ← All docs