Skip to main content
For what differs between this platform and the others, see Platform Support.
Bitbucket repositories are connected to Gitar by installing the Gitar Bitbucket app, built on Atlassian’s Forge platform. The app handles authentication, permissions, and webhook delivery, so there are no tokens or secrets to manage.

​
Prerequisites

  • A Gitar organization (not a personal account) with the Admin role
  • A Bitbucket account with access to the workspace you want to connect
  • Permission to install a Forge app on that Bitbucket workspace (workspace admin)

​
Setup Instructions

1

Open the connect dialog

In the Gitar dashboard, go to Settings → Configuration → Connections and click Connect Bitbucket (or use the “Connect your repositories” step during onboarding).
2

Connect your Bitbucket account

The first time you connect Bitbucket, Gitar asks you to authorize with your Bitbucket account via OAuth. This is a one-time step that lets Gitar list the workspaces you have access to.
3

Select the workspace

Choose the Bitbucket workspace you want to connect to this Gitar organization. Workspaces already connected to your organization are marked as such, and workspaces connected to a different Gitar organization show as “Connected to another organization”. A workspace can only be linked to one Gitar organization at a time.
4

Install the Forge app

Gitar opens a new browser tab to Atlassian, where you install the Gitar Forge app.
Atlassian asks you to pick a workspace to install on. You must pick the same workspace you selected in Gitar. Gitar has no way to match an install on a different workspace to your selection. The connection silently fails and the workspace you picked in Gitar never connects.
5

Return to Gitar and wait

Atlassian does not redirect you back to Gitar after installation. Switch back to the Gitar browser tab yourself.
While it waits, the dialog shows a “Waiting for installation…” state. Gitar detects the completed install within a few seconds up to about a minute. The connect dialog closes automatically once detected, and all repositories in the workspace are discovered and ready for review, with no per-repository picker to fill in.

​
Repository Access

Once connected, Gitar automatically discovers every repository in the workspace. Head to Settings → Configuration to see the full list and toggle individual repositories on or off.

​
Permissions

The Gitar Forge app requests the following capabilities: Gitar does not store your code. Code is checked out, processed, and discarded.

​
Limitations

​
A workspace can only belong to one Gitar organization

One Gitar organization can connect multiple Bitbucket workspaces, but each workspace can only be linked to one Gitar organization at a time. Trying to connect a workspace already claimed by another Gitar organization fails, and the workspace list marks it “Connected to another organization” instead of letting you pick it. If a workspace needs to move to a different Gitar organization, disconnect it from the first before connecting it in the second.

​
Token invalidation is detected reactively

Gitar authenticates to Bitbucket through the Forge app install rather than a token you manage, so there’s nothing to rotate on a schedule. The underlying access token can still stop working, most commonly because the Forge app was uninstalled or the workspace revoked access. Gitar notices either when its hourly token refresh fails or when a clone call fails, after a few consecutive failures, not the moment access is revoked. You do get told at that point. Gitar emails the organization’s admins and shows a dashboard notification pointing back to Settings → Configuration. Until the app is reinstalled or reconnected, incoming webhook events are dropped and pull requests in that workspace go unreviewed.

​
Troubleshooting

This usually means the install either was not completed on Atlassian, or was completed on a different workspace than the one selected in Gitar. Make sure you install the Forge app on the same workspace you selected in the Gitar dialog, then switch back to the Gitar tab. If the dialog already timed out, use Reopen install link to try again.
A Bitbucket workspace can only be linked to one Gitar organization at a time. If you need to connect it here, disconnect it from the other organization first.
Your Bitbucket account needs access to the workspace. Confirm you have access in Bitbucket, then reconnect your account from the Gitar dialog.
Confirm the Gitar Forge app is installed on the workspace and that the specific repository is enabled (toggled on) in the Settings → Configuration card.