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

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

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

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 type_3 = "HTTPS"

export const type_2 = "SSH"

export const type_1 = "SSH"

export const type_0 = "HTTPS"

export const introCopy_3 = "configure HTTPS token authentication"

export const provider_3 = "GitHub"

export const permission1_3 = "Create fine-grained personal access tokens that can access the repository"

export const permission2_3 = undefined

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

export const provider_2 = "GitHub"

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

export const permission2_2 = undefined

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

export const provider_1 = "GitHub"

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

export const permission2_1 = undefined

export const introCopy_0 = "configure GitHub App authentication"

export const provider_0 = "GitHub"

export const permission1_0 = "Install GitHub Apps on the repository or organization"

export const permission2_0 = undefined

Omni supports the following methods for connecting to a GitHub repository:

* **GitHub App authentication** - Uses a GitHub app to perform authentication. Enables commit signing.
* **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. 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 GitHub fine-grained access token to authenticate

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="GitHub App">
  ## 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 [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) for information about user permissions.

  <Note>
    GitHub App authentication is only available for `github.com` repositories. This option only appears if your Omni instance has the GitHub App configured. If you don't see this option and want to use it, reach out to Omni support.
  </Note>

  ## Configure GitHub App authentication

  In this guide, you'll set up GitHub App authentication using the Omni GitHub App.

  <Steps titleSize="h3">
    <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 **{type_0}** option.

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

    <Step title="Launch the Omni GitHub App installation flow">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      2. Click the model you want to connect to git.
      3. In the model IDE, click **Model > Git settings**.

      4) From the **Authentication Method** dropdown, select **GitHub App**.
      5) In the **HTTPS URL** field, copy and paste the repository's HTTPS URL from Step 1.
      6) Next to the **Installation ID** field, click the **Install the Omni GitHub App** link.

      GitHub will open in another tab in your browser. Leave this page open and finish the app installation in the other tab.
    </Step>

    <Step title="Install the Omni GitHub App">
      1. In GitHub, select the repository you want to connect.
      2. Complete the installation.
      3. After you complete the installation, retrieve the app's **installation ID** from the page URL:

               <Frame caption="The installation ID is the string of numbers after the final forward slash in the page URL. In this example, the ID is 149469922.">
                 <img src="https://mintcdn.com/omni-e7402367/FnnxljlPEokrSOpD/integrations/images/github-app-installation-id.png?fit=max&auto=format&n=FnnxljlPEokrSOpD&q=85&s=0d8403c6f6a112915dbaaf8a5d00448c" alt="Highlighted app installation ID in the page URL" width="1050" height="373" data-path="integrations/images/github-app-installation-id.png" />
               </Frame>

      The installation ID is the string of numbers after the last forward slash in the page URL.
    </Step>

    <Step title="Configure the Git settings in Omni">
      1. Navigate back to the Omni Git settings page.
      2. Finish configuring the integration's settings:

         * **Installation ID** - Paste the installation ID you copied from GitHub in the previous step
         * **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).

               <Note>
                 If you want to configure [commit signing](#configure-commit-signing), enter a **Committer name** and **Committer email**. You won't be able to change these after clicking **Configure git**.
               </Note>
      3. Click **Configure Git**.
    </Step>

    <Step title="Configure commit signing">
      <Note>
        This step is optional.
      </Note>

      Authenticating through Omni's GitHub app allows you to enable commit signing. When a user with a verified email adds Omni's public signing key, Omni's commits will show up as **Verified**.

      The user with the verified **Committer email** you defined in the previous step must complete the following to configure commit signing:

      1. In GitHub, navigate to **Settings > SSH and GPG keys**. **Note**: This is an individual **user's** settings, not the connected repository's settings.
      2. Click **New SSH key**.
      3. Set the **Key type** to **Signing key**.
      4. In the **Key** field, paste the public key from the Omni Git settings page.
      5. Click **Add SSH 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 sidebar.
      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>
</View>

<View title="SSH + Omni deploy 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 [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) 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">
      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 **{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** in the [sidebar](/administration/settings/sidebar).
      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">
      <Note>
        If the repository is already linked to another Omni model or connected through the [dbt integration](/integrations/dbt), skip this step. Omni will use the existing deploy key.
      </Note>

      1. In the GitHub repository, click the **Settings** tab.
      2. Click **Deploy keys**, located in the **Security** section of the sidebar.
      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** - {keyInstructions_0}
         * **Allow write access** - {writeAccess_0}
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      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 sidebar.
      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>
</View>

<View title="SSH + Your private key" id="ssh-your-private-key">
  ## 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_2} repository**
  * **Permissions in {provider_2} that allow you to:**
    * {permission1_2}
    * {permission2_2}

  Refer to [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) 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 GitHub 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="Connect the repository to Omni">
      1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
      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">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      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 GitHub repository, click the **Settings** tab.
      2. Click **Deploy keys**, located in the **Security** section of the sidebar.
      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** - {keyInstructions_1}
         * **Allow write access** - {writeAccess_1}
      5. Click **Add key**.
    </Step>

    <Step title="Add repository webhooks">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing webhook configuration.
      </Note>

      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 sidebar.
      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="Supply the private key to Omni with the API">
      <Note>
        If the repository is already linked to another Omni model, skip this step. Omni will use the existing deploy key.
      </Note>

      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_3}, 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_3}
    * {permission2_3}

  Refer to [GitHub's documentation](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) 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 GitHub repository you want to connect to Omni.
      2. Click the **Code** button.
      3. In the modal that displays, locate the **{type_3}** option.

      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** in the [sidebar](/administration/settings/sidebar).
      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.

## Related

* [Troubleshooting the Git integration](/integrations/git/troubleshooting)
* [Git best practices](/integrations/git/best-practices)
* [Rotate Git SSH deploy keys](/guides/api/rotate-ssh-deploy-keys)
* [Sync model with Git repository API](/api/model-git-configuration/sync-model-with-git-repository)