Skip to main content
For what differs between this platform and the others, see Platform Support.
Bitbucket Data Center support is in beta. For access or to leave feedback, email developers@gitar.ai.

​
Overview

Two paths connect a self-hosted instance, and you only need one. The Gitar app is a plugin you upload to your instance. It forwards pull request and build events to Gitar from inside Bitbucket, sets up its own credentials where Bitbucket allows it, and registers Gitar’s commit-signing key on the bot account so pushed commits show as Verified. This is the recommended path. A service-account token is the alternative: you create a user, generate an access token, and paste it into Gitar. Gitar then registers a webhook on each repository you connect. Use this if you would rather not install a plugin, or if your change-management process makes app installs slow. Bitbucket Data Center is different from Bitbucket Cloud, where Gitar installs through the Atlassian Marketplace. Forge is Cloud-only, so a self-hosted instance has no Marketplace install.

​
Prerequisites

  • A Bitbucket Data Center or Server 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 or air-gapped instances are not supported, so contact us if that applies to you.
  • Bitbucket administrator access, to install the app or to create a service account.

​
Option A: Install the Gitar app

1

Allow app uploads

Bitbucket 10 disables uploading apps through the admin UI by default, and checks app signatures. The Gitar app is a private build, so both need turning off before the upload will work. Add these to your instance’s JVM arguments and restart:
On Bitbucket Server 7.x and Data Center 8.x-9.x, neither flag is needed.
2

Upload the app

In Bitbucket, go to Administration → Manage apps → Upload app.Gitar’s connect dialog (Settings → Configuration → Bitbucket → Server) shows a copyable URL for each build. Paste it into the Upload from URL field. Two builds exist, and you need the one matching your version:
  • Bitbucket Data Center 10.x - the Jakarta build
  • Bitbucket Server 7.x / Data Center 8.x-9.x - the standard build
If your instance has no outbound internet access, download the JAR from the same dialog and pick it from disk instead.
3

Connect it with a code

The app runs inside your instance and cannot tell which Gitar organization installed it, so a one-time code is the whole handoff.
  1. In Gitar, go to Settings → Configuration → Bitbucket → Server and click Generate a connect code
  2. In Bitbucket, go to Administration → Gitar, paste the code, and click Connect
The code is single use and expires after 30 minutes. Generating a new one invalidates the old one, so the button is safe to click again if you lose the code.The app reports its own base URL and server ID, so there is nothing else to type. It also mints the bot account’s access token where Bitbucket permits it - version 10.x refuses to create a token on behalf of another user, and there the app’s own screen asks you to paste one instead.

​
Option B: Connect with a service-account token

1

Create a dedicated service account

Create a new user on your instance to act as the Gitar service account, for example 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 and reviews. Project Administrator permission is also required on projects where you want Gitar to register webhooks for you.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 or 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 register webhooks for you.
Set an expiration date and note it. Gitar stops working when the token expires and surfaces this in the dashboard as an unhealthy integration. To rotate, generate a new token with the same scopes, then Disconnect and reconnect the Server connection under Settings → Configuration → Bitbucket → Server with the new token.
4

Connect in Gitar

  1. In the Gitar dashboard, go to Settings → Configuration
  2. Click Connect next to Bitbucket, then open the Server tab
  3. Enter your instance’s base URL, for example https://bitbucket.yourcompany.com
  4. Select the token type (personal, or repository/project) and paste the token
  5. Select the projects 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. It then registers webhooks on the selected repositories automatically.If the service account lacks Project Administrator permission, Gitar reports which repositories failed webhook setup. Grant the permission and reconnect to retry.

​
Adding Repositories Later

Repositories created after you connect are not picked up automatically. Click Refresh on Settings → Configuration → Repositories to re-scan every connected instance. On a service-account connection this also registers a webhook on each new repository, which is what makes Gitar see its pull requests at all - so run it after creating a repository, not only when the list looks stale. Repositories deleted since the last scan are dropped from the list.

​
Network Reachability

Gitar’s data plane must be able to reach your instance’s REST API over HTTPS, and your instance must be able to send webhook requests to Gitar. If your instance enforces an IP allowlist, add Gitar’s public IP addresses to it. See Network Access for the addresses. Gitar has no outbound-only tunnel, so an instance with no route to the public internet cannot connect. Contact us if that is your setup.

​
Troubleshooting

On Bitbucket 10, app uploads are disabled by default and app signatures are checked. Add -Dupm.plugin.upload.enabled=true and -Datlassian.upm.signature.check.disabled=true to the JVM arguments and restart. If the upload is rejected as an incompatible plugin, you picked the wrong build - 10.x needs the Jakarta one.
The service account (or the token’s scope, if using a repository or project token) doesn’t have sufficient permission on the project or repository. Grant at least Read and Write, and Project Administrator if you want Gitar to register webhooks for you.
Click Refresh on Settings → Configuration → Repositories. On a service-account connection, a new repository has no webhook until this runs, so it delivers no events at all.
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. Generate a new token with the same scopes, then Disconnect and reconnect the Server connection under Settings → Configuration → Bitbucket → Server with the new token.
Gitar’s signing key isn’t registered on the bot account. The app registers it at connect time, so reconnecting through the app fixes this. On a service-account connection there is nothing to register the key, and commits stay unverified - this is cosmetic and doesn’t affect anything else.
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, Gitar reports which repositories failed webhook setup. Grant the permission and reconnect to retry.
Changing the base URL, for example moving to a new domain, breaks the integration because Gitar uses it to route API calls and validate webhook signatures. Disconnect and reconnect with the new URL. If you connected through the app, the app reports the new URL itself and Gitar moves the existing connection over.

​
Draft pull requests

The Skip draft PRs setting works on Bitbucket Data Center 10.x and later, which reports draft state on its pull request events. Earlier versions do not, so Gitar reviews drafts there regardless of the setting.