> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket Server

Gitpod works with public, private, or internal repositories on your own instance of [Bitbucket Server](https://bitbucket.org/product/guides/getting-started/overview#bitbucket-software-hosting-options) v7.20 or later. Setting this up requires 2 steps:

1. A one-time registration of the Bitbucket server instance with Gitpod.
2. Each Gitpod user connects their account to Bitbucket server the first time they start a workspace.

## Registering a Bitbucket Server

The Bitbucket Server Admin can register the Bitbucket Server in their own Gitpod [account settings](https://gitpod.io/user/integrations).

Start by creating a **New Integration** and entering the **Provider Host Name** of Bitbucket Server.

<Frame caption="Gitpod New Git Integration form">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-new-integration.png?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=7cfbbf37cdbfae3e5291009d559ae6c3" width="1920" height="1056" data-path="images/integrations/bbs-new-integration.png" />
</Frame>

Copy the **Redirect URL** from the form above.

Open your Bitbucket Server Administration settings in another browser tab, and create a new incoming link for an external application.

<Frame caption="Bitbucket Server new OAuth2 application link">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-new-incoming-link.png?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=bb264fc0bf06066cf7a99ac0ccb9f97e" width="931" height="642" data-path="images/integrations/bbs-new-incoming-link.png" />
</Frame>

Configure the link with the required fields, including the redirect URL copied above, and choose "Projects Admin" permissions.

<Frame caption="Bitbucket Server configure OAuth2 application link">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-configure-incoming-link.png?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=f93f03c74512857e046f464bfaafb476" width="1800" height="2166" data-path="images/integrations/bbs-configure-incoming-link.png" />
</Frame>

Saving the configuration opens a settings page where you can copy the OAuth **Client ID** and a **Client secret**.

<Frame caption="Bitbucket Server new OAuth client ID and secret">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-oauth-client-id-and-secret.png?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=1937a1d50cc29b053a7101b5e48826d8" width="1154" height="638" data-path="images/integrations/bbs-oauth-client-id-and-secret.png" />
</Frame>

Copy the **Client ID** and **Secret** into the corresponding fields in the new Gitpod integration form, and activate the integration.

Refreshing the integration settings page should show a new Git provider connection to your Bitbucket Server in addition to the Git Integration registration below that.

<Frame caption="Bitbucket Server integration and connection in Gitpod settings">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-integration-and-connection.png?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=029c0e8d42bce6f9573019c0aba06fb4" width="2206" height="1498" data-path="images/integrations/bbs-integration-and-connection.png" />
</Frame>

## Connecting Gitpod accounts to Bitbucket Server

Other Bitbucket Server users need to connect their own Gitpod account to their own Bitbucket Server account by starting a workspace.

To start a workspace, paste the URL of a Bitbucket Server repository into the New Workspace popup (`Ctrl/Cmd + O`) in Gitpod, or prefix the repository URL as described in [Getting started](/classic/user/introduction/getting-started/overview).

The first time you do this, you'll be prompted to authorize with your Bitbucket Server instance.

<Frame caption="Prompt to authorize with Bitbucket Server">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-unauthed-workspace-start.webp?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=6542817b544f06aaf52c48beb2f80f60" width="1494" height="1172" data-path="images/integrations/bbs-unauthed-workspace-start.webp" />
</Frame>

The Bitbucket Server OAuth window will prompt for confirmation to access projects and repositories.

<Frame caption="OAuth confirmation from Bitbucket Server">
  <img src="https://mintcdn.com/gitpod-13c83c2b/e8LRoo3UknjjGZet/images/integrations/bbs-oauth-popup.webp?fit=max&auto=format&n=e8LRoo3UknjjGZet&q=85&s=ab26abd6acd15bb4a6eb3549a9ce6ca4" width="2026" height="1526" data-path="images/integrations/bbs-oauth-popup.webp" />
</Frame>

Once confirmed, the connection will be saved, and the workspace should open. Subsequent workspaces with repositories from the same Bitbucket Server instance should open without reconnecting.