Skip to main content
Bitbucket Data Center support is currently in beta. For access or to leave feedback, please email us at: developers@gitar.ai

​
Overview

Gitar connects to self-hosted Bitbucket Data Center instances via an access token associated with a dedicated service account. Gitar uses this token to read pull requests, post review comments, and register webhooks that deliver events to Gitar in real time. Bitbucket Data Center is different from Bitbucket Cloud: there is no Atlassian Forge app for self-hosted instances, so the connection is token-based instead, similar to how Gitar connects to self-managed GitLab or Azure DevOps.

​
Prerequisites

  • A Bitbucket Data Center instance (version 7.x or later) reachable from Gitar’s network — an on-premises VPN, IP allowlist, or same-VPC/same-cloud connection. Fully firewalled/air-gapped instances are not yet supported; contact us if this applies to you.
  • Permission to create a service account (user) on your Bitbucket Data Center instance
  • Project Administrator permission on the projects you want to connect

​
Setup Instructions

1

Create a dedicated service account

Create a new user on your Bitbucket Data Center instance to act as the Gitar service account (e.g. gitar-bot).A dedicated account with a valid email address is required, not optional. Gitar identifies its own comments by the account that owns the token and ignores them to avoid processing its own output. The account also needs a valid email address — Bitbucket Data Center rejects pull request merges from users with no email set, which blocks Gitar’s auto-merge feature.
2

Grant project access

The service account needs at least Write permission on each project you want Gitar to access, so it can read pull requests and post comments/reviews. Project Administrator permission is additionally required on projects where you want Gitar to auto-provision webhooks during setup.For each project: go to Project settings → Permissions and add the service account with the appropriate role.
3

Generate an access token

Sign in as the Gitar service account and create a token. You can choose either:
  • A personal HTTP access token (scoped to everything the account can access) — go to your profile avatar → Manage account → Personal access tokens → Create token.
  • A repository or project access token (scoped to a single repo/project) — go to the repository or project’s Settings → Access tokens → Create token. Use this if you want to limit Gitar’s access to specific repositories rather than everything the service account can see.
Either way, grant Read and Write permission at the repository level (and Project admin if you want Gitar to auto-provision webhooks).
Set an expiration date and note it — Gitar will stop working when the token expires, and will surface this in the dashboard as an unhealthy integration. To rotate, generate a new token with the same scopes and update it under Settings → Integrations → Bitbucket Data Center → Update token.
4

Connect in Gitar

  1. In the Gitar dashboard, go to Settings → Integrations
  2. Click Connect next to Bitbucket Data Center
  3. Enter your instance’s base URL (e.g. https://bitbucket.yourcompany.com)
  4. Select the token type (personal vs. repository/project) and paste the token
  5. Select the projects/repositories you want Gitar to access
  6. Click Connect
Gitar validates the token (reachability, permissions, and — if you plan to use auto-merge — that the account has a valid email) and registers webhooks on the selected repositories automatically. If the service account lacks Project Administrator permission, Gitar shows the webhook URL and secret for manual setup instead.

​
Network reachability

Gitar’s data plane must be able to reach your Bitbucket Data Center instance’s REST API over HTTPS, and your instance must be able to send webhook requests to Gitar. If your instance is behind a firewall with no route to the public internet, reach out — outbound-only tunnel connectivity for fully firewalled instances is on our roadmap but not yet available.

​
Troubleshooting

The service account (or the token’s scope, if using a repository/project token) doesn’t have sufficient permission on the project or repository. Grant at least Read & Write, and Project Administrator if you want automatic webhook setup.
The service account has no email address set, or an invalid one. Bitbucket Data Center rejects merges from accounts without a valid email — set one on the service account and reconnect.
The access token has likely expired. Go to Settings → Integrations → Bitbucket Data Center, click Update token, and paste a newly generated token.
Confirm your instance can reach Gitar’s webhook endpoint over the public internet (or your configured private connection), and that no corporate proxy is stripping the X-Hub-Signature header. If the service account lacks Project Administrator permission, webhooks must be registered manually — check Settings → Integrations → Bitbucket Data Center for the webhook URL and secret to configure yourself.
Changing the base URL (e.g. moving to a new domain) breaks the integration because Gitar uses it to route API calls and validate webhook signatures. Reconnect from Settings → Integrations → Bitbucket Data Center → Disconnect, then reconnect with the new URL.