Bitbucket Server / Data Center Integration

Connect Codeveira to your self-hosted Bitbucket Server or Bitbucket Data Center instance to automatically open a code review on every push — using an HTTP access token and a webhook on the repo:refs_changed event.

Prerequisites

Bitbucket Server 7.0+ or Bitbucket Data Center (self-hosted)
An HTTP access token or a username and password with repository read access
Network access between your Codeveira instance and your Bitbucket Server (both HTTPS and webhooks must be reachable)
Codeveira admin access to add repositories and set environment variables

This guide covers self-hosted Bitbucket Server and Bitbucket Data Center. If you are using the cloud service at bitbucket.org, see the Bitbucket Cloud guide instead.

How Codeveira integrates with Bitbucket Server

Codeveira connects to your self-hosted Bitbucket Server or Data Center instance in two ways: a read-only REST API connection to fetch commit data, and a webhook to trigger code review creation automatically on every push.

Read-only API access

Codeveira authenticates using an HTTP access token (or username:password basic auth) against the Bitbucket Server REST API. Every API call is read-only — Codeveira never pushes code, creates pull requests, or modifies anything in your Bitbucket Server instance. The token is used to:

Fetch commit metadata: author, message, timestamp and parent commit hashes
Download the diff for each commit in unified diff format
Retrieve repository and project information
Read raw file content for syntax-highlighted diff display

HTTP access tokens are the recommended credential type because they can be revoked independently, scoped to a single permission level, and do not require storing your account password. Codeveira only needs Repository: Read (or Projects: Read) permission.

Automatic review creation via webhooks

The webhook you configure in Step 4 fires a repo:refs_changed event on every push. Codeveira receives the event at /webhooks/bitbucket_server and:

Reads the list of updated refs and their new commit SHAs from the event payload
Fetches the commits introduced by the push via the Bitbucket Server REST API
Groups consecutive commits by the same author into a single code review
Creates the review, fetches the full diff, and stores it in Codeveira
Sends email notifications to assigned reviewers and triggers the AI reviewer bot if configured

Both Codeveira and Bitbucket Server must be able to reach each other over the network. Codeveira makes outbound API calls to Bitbucket Server, and Bitbucket Server makes outbound webhook calls to Codeveira. Check your network rules if either direction is blocked.

Create an HTTP access token

HTTP access tokens are the recommended authentication method for Bitbucket Server. To create one:

Click your avatar in the top-right corner of Bitbucket Server
Go to Manage account
Select HTTP access tokens in the left sidebar
Click Create token
Give it the name Codeveira
Set permissions: Repository read (or Projects: read — both are sufficient)
Click Create and copy the token immediately

Alternatively you can use username:password Basic auth — enter it in the same Token field as username:password. HTTP access tokens are preferred because they can be revoked independently without changing your account password.

Find your project key and repo slug

Bitbucket Server uses a project key and a repository slug to identify repositories. Both are visible in the repository URL:

https://bitbucket.example.com/projects/PROJ/repos/my-repo

Project key: PROJ — always uppercase, shown after /projects/
Repo slug: my-repo — shown after /repos/

In Codeveira the Path field must be PROJECTKEY/repo-slug, for example:

PROJ/my-repo

Project keys are case-sensitive and must be entered in uppercase exactly as they appear in the URL.

Add the repository in Codeveira

Go to Repositories → New Repository
Click the Bitbucket Server platform button
Fill in the fields:

Name — display name for this repository in Codeveira
Instance URL (required) — base URL of your Bitbucket Server, e.g. https://bitbucket.example.com
Path — PROJECTKEY/repo-slug, e.g. PROJ/my-repo
Token — HTTP access token from Step 1, or username:password

Click Save. Codeveira will immediately attempt a test API call to verify the credentials and path — after that, the first push will automatically open a code review.

Configure the webhook

Webhooks allow Codeveira to automatically create a code review on every push without polling.

In Bitbucket Server, navigate to your repository
Go to Repository settings → Webhooks → Create webhook
Set the following values:

Name: Codeveira
URL: https://codeveira.yourdomain.com/webhooks/bitbucket_server
Secret: generate a secret and save it (see below)
Events: check Push (event key repo:refs_changed)

Generate a strong secret and set it in your .env:

openssl rand -hex 20
# Copy the output, then add to .env:
BITBUCKET_SERVER_WEBHOOK_SECRET=your_generated_secret

After updating .env, restart the application:

docker compose up -d app

Bitbucket Server sends an X-Hub-Signature header (HMAC-SHA256) when a secret is configured. Without BITBUCKET_SERVER_WEBHOOK_SECRET set in Codeveira, any payload is accepted — always set it in production to prevent spoofed events.

Troubleshooting

SSL certificate errors

Bitbucket Server installations often use a self-signed certificate. Codeveira's Docker container may reject it. Two options:

Mount your CA certificate into the container and add it to the system trust store
Use an internal HTTP URL if Codeveira and Bitbucket Server are on the same network

"Project not found" when saving a repository

The project key is case-sensitive and must be uppercase. Check the Bitbucket Server URL bar — the key appears in the path as /projects/PROJ/. A lowercase or partial match will result in a 404 from the API.

Webhook returns 401 Unauthorized

This means the HMAC signature does not match. The most common causes are:

The secret in Bitbucket Server does not match BITBUCKET_SERVER_WEBHOOK_SECRET in your .env
The .env was updated but the container was not restarted

Regenerate the secret, update both Bitbucket Server's webhook configuration and BITBUCKET_SERVER_WEBHOOK_SECRET, then restart: docker compose up -d app.

← All docs Next: Azure DevOps Integration →