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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/integrations/git/setup/gitlab",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# GitLab

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

export const token_0 = "GitLab project access token"

export const provider_0 = "GitLab"

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

export const permission2_0 = "For HTTPS token authentication: Create project access tokens"

Omni supports two methods for connecting to GitLab 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 GitLab.
* **HTTPS token authentication** — Uses a GitLab project access token to authenticate. This method is simpler to set up because it doesn't require deploy keys or webhooks.

Both methods are covered in the [Setup](#setup) section below. Choose the method that best fits your team's security requirements and preferences.

## Requirements

To follow the steps in this guide, you'll need:

* [**Omni Connection Admin permissions**](/administration/users/permissions) for the 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 [GitLab's documentation](https://docs.gitlab.com) for information about user permissions.

## Setup

<Note>
  Click the tab for the authentication method you want to use to view setup instructions.
</Note>

<Tabs>
  <Tab title="SSH authentication">
    <Steps>
      <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 **SSH** 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** - Copy the **Public key** from the Omni **Git settings** page and paste it into this field.
           * **Grant write permissions to this key** - Check this box, which will allow Omni to push changes made in Omni to the repository
        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>
  </Tab>

  <Tab title="HTTPS token authentication">
    <Steps>
      <Step title="Retrieve the repository's HTTPS 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 **HTTPS** option and copy the URL.

        Keep this page open - you'll need it to complete the setup in Omni.
      </Step>

      <Step title="Create a project access token" noAnchor>
        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" 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 **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" 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>
  </Tab>
</Tabs>

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