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

# Bitbucket Integration

> Add deploy keys to Bitbucket repositories for Coalesce Quality

## Overview

This guide covers how to add the generated public SSH key as an access key (deploy key) to your Bitbucket repository.

<Info>
  **Before you start:** Create your Git integration first by following the [integration form instructions](/code-integrations/overview#configuring-the-integration). You'll need the public SSH key from that integration.
</Info>

## Prerequisites

* Access to Bitbucket Cloud or Bitbucket Server/Data Center
* **Admin access** to your repository (required to add access keys)
* Public SSH key from your Git integration

<Note>
  ⏱️ **Estimated time:** 5 minutes
</Note>

## IP Whitelisting (If Required)

If your Bitbucket workspace uses IP allowlisting, add the Coalesce Quality egress IP addresses for your region. See [IP Whitelist](/security/ip) for the complete list.

For instructions on configuring IP allowlisting in Bitbucket, see Bitbucket's guide on [IP allowlisting](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/).

## Adding the Access Key

<Tabs defaultValue="cloud">
  <TabsList>
    <TabsTrigger value="cloud">Bitbucket Cloud</TabsTrigger>
    <TabsTrigger value="server">Bitbucket Server/Data Center</TabsTrigger>
  </TabsList>

  <TabsContent value="cloud">
    ### Bitbucket Cloud

    Follow these steps to add an access key (deploy key) to your Bitbucket Cloud repository.

    #### Navigate to Repository Settings

    1. Go to your repository in Bitbucket Cloud
    2. Click **Repository settings** (gear icon in the left sidebar)

    #### Add Access Key

    3. Under **Security**, click **Access keys**
    4. Click **Add key**
    5. Configure the access key:
       * **Label:** Enter a descriptive name (e.g., `Coalesce Quality Integration`)
       * **Key:** Paste the public SSH key from your integration

    <Warning>
      **Do not enable write access.** Only read-only access is required.
    </Warning>

    6. Click **Add SSH key**

    That's it! Your Bitbucket repository is now connected in read-only mode.

    #### Documentation

    For more details, see Bitbucket's official guide on [Access Keys](https://support.atlassian.com/bitbucket-cloud/docs/add-access-keys/).
  </TabsContent>

  <TabsContent value="server">
    ### Bitbucket Server/Data Center

    Follow these steps to add an access key to your Bitbucket Server or Data Center repository.

    #### Navigate to Repository Settings

    1. Navigate to your repository in Bitbucket Server
    2. Click **Repository settings** in the left sidebar

    #### Add Access Key

    3. Under **Security**, click **Access keys**
    4. Click **Add key**
    5. Configure the access key:
       * **Key:** Paste the public SSH key from your integration
       * **Permission:** Set to **Read** only

    <Warning>
      **Set permissions to Read only.** Write access is not required.
    </Warning>

    6. Click **Add key**

    The access key is now active. Your Bitbucket repository is connected in read-only mode.

    #### Documentation

    For more details, see Bitbucket's documentation on [SSH Access Keys](https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html).
  </TabsContent>
</Tabs>

## Repository URL Format

When configuring the integration, use the SSH URL format for Bitbucket:

**Format:** `git@bitbucket.org:workspace/repository.git`

**Example:** `git@bitbucket.org:mycompany/analytics-platform.git`

For Bitbucket Server/Data Center, the format may vary:

* `git@bitbucket.example.com:project/repository.git`
* `ssh://git@bitbucket.example.com:7999/project/repository.git`

## Troubleshooting

### Access key not working

* Verify the **complete public key** was copied (including the `ssh-rsa` or `ssh-ed25519` prefix)
* Ensure the access key was added to the **correct repository**
* Confirm the key has **read-only permissions**

### Connection refused

* Check that your workspace's **IP allowlist** (if configured) includes the Coalesce Quality egress IPs
* Verify the repository **SSH URL** is correct in the integration form
* For **Bitbucket Server**, ensure the instance is accessible from the Coalesce Quality IP addresses

### No Repository Settings visible

* Confirm you have **admin access** to the repository
* Check with your Bitbucket administrator for access permissions

### SSH URL format issues

* Bitbucket Cloud uses: `git@bitbucket.org:workspace/repo.git`
* Bitbucket Server may use a custom port: `ssh://git@hostname:7999/project/repo.git`
* Do not use HTTPS URLs - only SSH URLs are supported

## Additional Resources

* [Bitbucket Cloud Access Keys Documentation](https://support.atlassian.com/bitbucket-cloud/docs/add-access-keys/)
* [Bitbucket Server SSH Access Keys](https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html)
* [Bitbucket IP Allowlisting](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/)
* [Back to Integration Overview](/code-integrations/overview)