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

# GitHub

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

export const token_0 = "GitHub fine-grained personal access token"

export const provider_0 = "GitHub"

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

export const permission2_0 = "For HTTPS token authentication: Create fine-grained personal access tokens that can access the repository"

Omni supports two methods for connecting to GitHub 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 GitHub.
* **HTTPS token authentication** — Uses a GitHub fine-grained 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 [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) 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">
        1. In your browser, navigate to the GitHub 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">
        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">
        1. In the GitHub repository, click the **Settings** tab.
        2. Click **Deploy keys**, located in the **Security** section of the left navigation.
        3. Click **Add deploy key**.
        4. Fill in the 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.
        * **Allow write access** - Check this box, which will allow Omni to push changes made in Omni to the repository

        5. Click **Add key**.
      </Step>

      <Step title="Add repository webhooks">
        1. The repository settings page should still be open in GitHub. If not, re-open it.
        2. Click **Webhooks**, located in the **Code and automation** section of the left navigation.
        3. Click **Add webhook**.
        4. Fill in the fields as follows:

        * **Payload URL** - From the Omni **Git settings** page, copy the **Payload URL** and paste it into this field.
        * **Content type** - Select the **application/json** option.
        * **Secret** - From the Omni **Git settings** page, copy the **Webhook secret** and paste it into this field.

        5. In the **Which events would you like to trigger this webhook?** section:
        6. Click **Let me select individual events**.
        7. Select the **Pull request** event.
        8. If the **Push** event is selected, deselect it.
        9. When finished, click **Add webhook**.
      </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>
  </Tab>

  <Tab title="HTTPS token authentication">
    <Steps>
      <Step title="Retrieve the repository's HTTPS URL">
        1. In your browser, navigate to the GitHub 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 in the next step.
      </Step>

      <Step title="Create a GitHub fine-grained personal access token">
        <Note>
          If the repository belongs to an organization, the organization must have a [personal access token policy](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) that allows the creation of personal access tokens.
        </Note>

        In GitHub, create a fine-grained personal access token with the following permissions for the repository:

        * **Contents**: Read and write
        * **Metadata**: Read-only (automatically included)
        * **Pull requests**: Read and write

        See [GitHub's documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) for instructions on creating a fine-grained personal access token.
      </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">
        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.