> ## 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 GitLab repository to Omni

> Connect a GitLab repository to an Omni model using SSH deploy keys or HTTPS token authentication

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

export const writeAccess_1 = "Check this box, which will allow Omni to push changes made in Omni to the repository"

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

export const writeAccess_0 = "Check this box, which will allow Omni to push changes made in Omni to the repository"

export const token_0 = "GitLab project access token"

export const type_2 = "HTTPS"

export const type_1 = "SSH"

export const type_0 = "SSH"

export const introCopy_2 = "configure HTTPS token authentication"

export const provider_3 = "GitLab"

export const permission1_2 = "Create project access tokens"

export const permission2_2 = undefined

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

export const provider_2 = "GitLab"

export const permission1_1 = "Add webhooks and deploy/SSH keys to repositories"

export const permission2_1 = undefined

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

export const provider_1 = "GitLab"

export const permission1_0 = "Add webhooks and deploy/SSH keys to repositories"

export const permission2_0 = undefined

export const provider_0 = "GitLab"

export const tokenType_0 = "project access token"

Omni supports the following methods for connecting to {provider_0} repositories:

* **SSH authentication** — Uses a deploy key and webhooks to connect Omni to your repository. This is the traditional method and requires configuring both a deploy key and a webhook in {provider_0}. You can either:
  * Use the deploy key Omni generates by default
  * Generate your own keypair and supply Omni with the private key
* **HTTPS token authentication** — Uses a {provider_0} {tokenType_0} to authenticate. This method is simpler to set up because it doesn't require deploy keys or webhooks.

Choose the method that best fits your team's security requirements and preferences.

<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_1} repository**
  * **Permissions in {provider_1} that allow you to:**
    * {permission1_0}
    * {permission2_0}

  Refer to [GitLab's documentation](https://docs.gitlab.com) for information about user permissions.

  ## Configure SSH authentication with an Omni deploy key

  In this guide, you'll set up SSH authentication that uses the deploy key Omni generates for you.

  <Steps titleSize="h3">
    <Step title="Retrieve the repository's SSH URL" noAnchor>
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the **{type_0}** option.

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

    <Step title="Connect the repository to Omni" noAnchor>
      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 deploy key" noAnchor>
      <Tip>
        **Connecting to a repository that's already linked to another Omni model?** Skip to Step 5—the repository's deploy key and webhooks should already be configured.
      </Tip>

      1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
               <Note>
                 GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
               </Note>
      2. Fill in the deploy key fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** - {keyInstructions_0}
         * **Grant write permissions to this key** - {writeAccess_0}
      3. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks" noAnchor>
      1. The repository settings page should still be open in GitLab. If not, re-open it.
      2. Click **Webhooks**.
      3. Click **Add new webhook**.
      4. Fill in the fields as follows:
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret token** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Custom headers** section:
         1. Click **Add custom header**.
         2. In the **Header name** field, enter `Content_type`.
         3. In the **Header value** field, enter `application/json`.
      6. In the **Trigger** section, select **Merge request events**.
      7. When finished, click **Add webhook**.
    </Step>

    <Step title="Test the connection" noAnchor>
      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_2} repository**
  * **Permissions in {provider_2} that allow you to:**
    * {permission1_1}
    * {permission2_1}

  Refer to [GitLab's documentation](https://docs.gitlab.com) 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 GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the **{type_1}** option.

      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. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
               <Note>
                 GitLab recommends using a [service account](https://docs.gitlab.com/user/profile/service_accounts/) when creating a deploy key so that the key will be unaffected if the [user leaves the organization](https://docs.gitlab.com/user/profile/service_accounts/).
               </Note>
      2. Fill in the deploy key fields as follows:
         * **Title** - Enter a descriptive title to help you identify what the key is used for. For example, *Omni Snowflake Model*
         * **Key** - {keyInstructions_1}
         * **Grant write permissions to this key** - {writeAccess_1}
      3. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      1. The repository settings page should still be open in GitLab. If not, re-open it.
      2. Click **Webhooks**.
      3. Click **Add new webhook**.
      4. Fill in the fields as follows:
         * **URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
         * **Secret token** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.
      5. In the **Custom headers** section:
         1. Click **Add custom header**.
         2. In the **Header name** field, enter `Content_type`.
         3. In the **Header value** field, enter `application/json`.
      6. In the **Trigger** section, select **Merge request events**.
      7. When finished, click **Add webhook**.
    </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>

<View title="HTTPS token authentication">
  ## Requirements

  To {introCopy_2}, you'll need:

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

  Refer to [GitLab's documentation](https://docs.gitlab.com) for information about user permissions.

  ## Configure HTTPS token authentication

  In this guide, you'll set up HTTPS token authentication.

  <Steps titleSize="h3">
    <Step title="Retrieve the repository's HTTPS URL">
      1. In your browser, navigate to the GitLab repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the **{type_2}** option.

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

    <Step title="Create a project access token">
      In the GitLab repository, create a project access token with the following [project scopes](https://docs.gitlab.com/user/project/settings/project_access_tokens/#project-access-token-scopes):

      * `api` - Full API access
      * `read_repository` - Read repository contents
      * `write_repository` - Write repository contents

      See the [GitLab documentation](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token) for token creation steps.
    </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 **HTTPS (Token)** from the dropdown.
         * **HTTPS URL** - Copy and paste the repository's **HTTPS URL** from Step 1.
         * **Access Token** - Paste the {token_0} from Step 2.
         * **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**.
    </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>

## 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.