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

# Connect a Bitbucket Data Center/Server repository to Omni

> Connect a self-hosted Bitbucket Data Center or Server repository to an Omni model

export const keyInstructions_1 = "Paste the contents of the omni_deploy_key.pub file from the previous step"

export const keyInstructions_0 = "Copy the public key from the Omni Git settings page and paste it into this field."

export const introCopy_1 = "configure SSH with your own private key"

export const provider_1 = "Bitbucket"

export const permission1_1 = "Add webhooks to repositories"

export const permission2_1 = "Add access keys to repositories"

export const introCopy_0 = "configure SSH with an Omni deploy key"

export const provider_0 = "Bitbucket"

export const permission1_0 = "Add webhooks to repositories"

export const permission2_0 = "Add access keys to repositories"

<Note>
  Multiple Omni models can share the same git repository. If you're connecting a model to a repository that's already connected to another model, you only need to complete the Omni-side setup—the repository's deploy key and webhooks are already configured.
</Note>

Omni supports SSH authentication to connect to Bitbucket Data Center or Server repositories. This requires configuring both a deploy key and a webhook in Bitbucket. For the deploy key, you can either:

* Use the deploy key Omni generates by default
* Generate your own keypair and supply Omni with the private key

<View title="Select authentication method">
  ## Select an authentication method

  <Note>
    To view instructions, select the authentication method you want to use from the **dropdown menu** on the right side of the page, above the table of contents.

    <Frame caption="Select your authentication method from the dropdown to view setup instructions">
      <img src="https://mintcdn.com/omni-e7402367/z4NfWcJoMfO93ijI/integrations/images/git-select-auth-method.png?fit=max&auto=format&n=z4NfWcJoMfO93ijI&q=85&s=e95edc19fad7856990cb7b855fa72e2c" alt="Authentication method selection menu on right side of this page" width="278" height="170" data-path="integrations/images/git-select-auth-method.png" />
    </Frame>
  </Note>
</View>

<View title="SSH + Omni deploy key">
  ## Requirements

  To {introCopy_0}, you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing {provider_0} repository**
  * **Permissions in {provider_0} that allow you to:**
    * {permission1_0}
    * {permission2_0}

  Refer to [Bitbucket's documentation](https://confluence.atlassian.com/bitbucketserver/users-and-groups-776640439.html) for information about user permissions.

  <Steps titleSize="h3">
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Bitbucket repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. In the modal that displays, click the **HTTPS** dropdown, then select **SSH**.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop**.
      2. Click the model you want to connect to git.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Add a repository access key">
      1. In the Bitbucket repository, click **Repository settings**.
      2. Click **Access keys**, located in the left navigation.
      3. Click **Add key**.
      4. Fill in the fields as follows:
         * **Key** - {keyInstructions_0}
         * **Permission** - Select **Write** to allow Omni to push changes made in Omni to the repository
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      1. If the repository settings page isn't still open, open it by clicking **Repository settings** in the left navigation.
      2. Click **Webhooks**, located in the **Workflow** section of the left navigation.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title, such as *Omni Pull Request Webhook*
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Triggers** section, select **Choose from a full list of triggers**.
      6. Select only the **Pull Request** events:
         * Pull Request Created
         * Pull Request Updated
         * Pull Request Merged
      7. When finished, click **Save**.
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.
    </Step>
  </Steps>
</View>

<View title="SSH + Your private key" id="ssh-your-private-key">
  ## Requirements

  To {introCopy_1}, you'll need:

  * [**Connection Admin permissions**](/administration/users/permissions) for the Omni model you want to connect to git
  * **An existing {provider_1} repository**
  * **Permissions in {provider_1} that allow you to:**
    * {permission1_1}
    * {permission2_1}

  Refer to [Bitbucket's documentation](https://confluence.atlassian.com/bitbucketserver/users-and-groups-776640439.html) for information about user permissions.

  To generate the keypair and supply the private key to Omni, you'll also need:

  * An [Omni API key](/api/authentication)
  * **The shared model's `modelId`,** which you can retrieve using the [List models](/api/models/list-models) endpoint
  * **`ssh-keygen` installed locally** to generate keypairs

  ## Configure SSH authentication with your private key

  In this guide, you'll set up SSH authentication that uses the private key you generate as part of a public-private keypair.

  <Steps titleSize="h3">
    <Step title="Retrieve the repository's SSH URL">
      1. In your browser, navigate to the Bitbucket repository you want to connect to Omni.
      2. Click the **Clone** button near the top right corner of the page.
      3. In the modal that displays, click the **HTTPS** dropdown, then select **SSH**.

      Keep this page open—you'll need it in the next step.
    </Step>

    <Step title="Connect the repository to Omni">
      1. In Omni, click **Develop**.
      2. Click the model you want to connect to git.
      3. In the model IDE, click **Model > Git settings**.
      4. You'll be prompted to enter connection details for the repository:
         * **Authentication Method** - Select **SSH (Deploy Key)** from the dropdown.
         * **SSH URL** - Copy and paste the repository's SSH URL from Step 1.
         * **Base Branch** - Enter the name of the default branch for the repository. Omni will default to `main` unless a different name is specified.
         * **Git follower** - Select this option if the repository should be treated as a [follower](/integrations/git/follower-mode).
      5. Click **Configure Git**.

      The page will update to display additional git settings, including information for deploy keys and webhooks.
    </Step>

    <Step title="Generate a new keypair">
      Use `ssh-keygen` to generate a new RSA or ED25519 keypair.

      <Tabs>
        <Tab title="ED25519">
          ```bash wrap theme={null}
          ssh-keygen -t ed25519 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>

        <Tab title="RSA">
          ```bash wrap theme={null}
          ssh-keygen -t rsa -b 4096 -C "omni-deploy-key-rotation-$(date +%Y%m%d)" -f omni_deploy_key
          ```
        </Tab>
      </Tabs>

      When prompted for a passphrase:

      * **To leave the key unencrypted**, press `Enter`.
      * **To encrypt the key**, provide a passphrase. This is more secure at rest, but you'll need to supply it to Omni.

      This generates two files:

      * `omni_deploy_key` — The private key, which you'll supply to Omni
      * `omni_deploy_key.pub` — The public key, which you'll authorize with your Git provider
    </Step>

    <Step title="Add a repository deploy key">
      Add the public key (`omni_deploy_key.pub`) to your Git repository as a deploy key with **write access**. This step ensures the new key is authorized before you supply the private key to Omni.

      1. In the Bitbucket repository, click **Repository settings**.
      2. Click **Access keys**, located in the left navigation.
      3. Click **Add key**.
      4. Fill in the fields as follows:
         * **Key** - {keyInstructions_1}
         * **Permission** - Select **Write** to allow Omni to push changes made in Omni to the repository
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      1. If the repository settings page isn't still open, open it by clicking **Repository settings** in the left navigation.
      2. Click **Webhooks**, located in the **Workflow** section of the left navigation.
      3. Click **Add webhook**.
      4. Fill in the fields as follows:
         * **Title** - Enter a descriptive title, such as *Omni Pull Request Webhook*
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Triggers** section, select **Choose from a full list of triggers**.
      6. Select only the **Pull Request** events:
         * Pull Request Created
         * Pull Request Updated
         * Pull Request Merged
      7. When finished, click **Save**.
    </Step>

    <Step title="Supply the private key to Omni with the API">
      Next, call the [Update Git configuration](/api/model-git-configuration/update-git-configuration) API and provide the private key.

      <Tabs>
        <Tab title="Unencrypted keys">
          In the terminal, navigate to the same location where the `omni_deploy_key` file was saved. Then, run the following:

          ```bash wrap theme={null}
          curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
            -H "Authorization: Bearer <YOUR_API_TOKEN>" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg key "$(cat omni_deploy_key)" '{deployPrivateKey: $key}')"
          ```

          Replace the following variables:

          * `<your-subdomain>` - Your Omni subdomain
          * `<MODEL_ID>` - The shared model's UUID
          * `<YOUR_API_TOKEN>` - Your Omni API key

          A successful response will include the derived public key in the `publicKey` field.
        </Tab>

        <Tab title="Passphrase-protected keys">
          1. In the terminal, navigate to the same location where the `omni_deploy_key` file was saved.
          2. Run the following to create a plain shell variable for the passphrase:

             ```bash wrap theme={null}
             printf "Passphrase: " && read -rs DEPLOY_KEY_PASSPHRASE && echo
             ```
          3. When prompted, enter the passphrase.
          4. Then, run the following to supply Omni with the private key and passphrase:

             ```bash wrap theme={null}
             curl -X PATCH https://<your-subdomain>.omniapp.co/api/v1/models/<MODEL_ID>/git \
               -H "Authorization: Bearer <YOUR_API_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "$(jq -n \
                     --arg key "$(cat omni_deploy_key)" \
                     --arg passphrase "$DEPLOY_KEY_PASSPHRASE" \
                     '{deployPrivateKey: $key, deployKeyPassphrase: $passphrase}')"
             ```

             Replace the following:

             * `<your-subdomain>` - Your Omni subdomain
             * `<MODEL_ID>` - The shared model's UUID
             * `<YOUR_API_TOKEN>` - Your Omni API key

             A successful response will include the derived public key in the `publicKey` field.
          5. After you receive a successful response, run the following to unset the passphrase variable:

             ```bash theme={null}
             unset DEPLOY_KEY_PASSPHRASE
             ```
        </Tab>
      </Tabs>

      <Note>
        If you run into issues, see the [Troubleshooting section in the Rotate Git SSH keys guide](/guides/api/rotate-ssh-deploy-keys#troubleshooting).
      </Note>
    </Step>

    <Step title="Test the connection">
      To verify the setup, navigate back to the **Git settings** page in Omni. Click the **Test git connection** button near the top of the page to test the connection.

      <Tip>
        **Need to rotate keys?** See [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys) for step-by-step instructions.
      </Tip>
    </Step>
  </Steps>
</View>

## What's next?

After the setup is complete, you can configure the integration's behavior by changing its settings. Refer to the [git integration settings reference](/integrations/git/settings) for more information.