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

# GitHub

> Connect GitHub repositories to Omni for unified search across code, issues, pull requests, and discussions

The GitHub connector enables Omni to index and search content from your GitHub organization, including repositories, issues, pull requests, and discussions.

## Overview

### What Gets Indexed

| Source        | Content                                              |
| ------------- | ---------------------------------------------------- |
| Repositories  | Repository names, descriptions, and README files     |
| Issues        | Issue titles, descriptions, comments, and labels     |
| Pull Requests | PR titles, descriptions, review comments, and status |
| Discussions   | Discussion threads and replies                       |

### How It Works

1. A GitHub Personal Access Token (PAT) grants Omni read-only access to your repositories
2. The connector syncs content from repositories the authenticated user has access to
3. Permission inheritance ensures users only see content from repositories they can access in GitHub

<Note>
  The connector uses read-only access. Omni cannot modify any content in your GitHub repositories.
</Note>

## Prerequisites

Before setting up the GitHub connector, ensure you have:

* **GitHub account** with access to the repositories you want to index
* **GitHub organization admin access** (recommended for org-wide indexing)
* **Omni deployment** with the GitHub connector service running

## Setup

### Step 1: Create a Personal Access Token

1. Go to **GitHub Settings** → **Developer settings** → **Personal access tokens** → **Fine-grained tokens**
2. Click **Generate new token**
3. Fill in the token details:
   * **Token name**: `Omni Search`
   * **Expiration**: Choose an appropriate expiration (or set a custom date)
   * **Repository access**: Select the repositories you want Omni to index (or **All repositories** for org-wide indexing)
4. Under **Permissions**, grant **read-only** access to:
   * **Repository permissions**: `Contents` (read), `Issues` (read), `Pull requests` (read), `Discussions` (read), `Metadata` (read)
5. Click **Generate token**
6. Copy the token immediately — you won't be able to see it again

<Warning>
  Store your Personal Access Token securely. Anyone with access to this token can read data from your GitHub repositories.
</Warning>

### Step 2: Connect in Omni

1. Navigate to **Settings** → **Integrations** in Omni
2. Find **GitHub** and click **Connect**
3. Paste your Personal Access Token into the token field
4. Click **Connect**
5. Click **Sync Now** to start the initial sync

<Check>
  Your GitHub connector is now configured. Initial indexing may take a while depending on the number of repositories and issues in your organization.
</Check>

## Managing the Integration

### Viewing Sync Status

Navigate to **Settings** → **Integrations** to view the sync status for each source directly on the list, including last sync time, number of indexed items, and any errors. Click **Configure** on a source for more details.

### Sync Modes

The GitHub connector supports two sync modes:

| Mode            | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| **Full**        | Syncs all content from all accessible repositories (used for initial sync) |
| **Incremental** | Syncs only new or updated content since last sync (used for updates)       |

After the initial full sync, the connector automatically performs incremental syncs to capture new activity.

### Removing the Integration

1. Navigate to **Settings** → **Integrations**
2. Click **Configure** against the GitHub source
3. Click **Delete Permanently**
4. Optionally, delete the Personal Access Token in your [GitHub settings](https://github.com/settings/tokens)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Repositories not appearing in search">
    Common causes:

    * The authenticated user doesn't have access to the repository
    * Sync has not completed yet
    * The repository is archived and may need explicit inclusion

    **Solution**: Verify repository access and trigger a manual sync.
  </Accordion>

  <Accordion title="Authentication failed">
    The Personal Access Token may be expired or revoked.

    **Solution**:

    1. Navigate to **Settings** → **Integrations** → **GitHub**
    2. Click **Update Token** to enter a new Personal Access Token
  </Accordion>

  <Accordion title="Rate limiting errors">
    GitHub has API rate limits. The connector handles these automatically with backoff.

    **Solution**: Wait for the connector to retry. For large organizations, initial sync may take longer due to rate limits.
  </Accordion>

  <Accordion title="Private repository content not indexed">
    Ensure the Personal Access Token has access to private repositories.

    **Solution**: Verify the token has `Contents` (read) permission and that the repository is included in the token's repository access scope. If needed, regenerate the token with the correct permissions and update it in Omni.
  </Accordion>

  <Accordion title="Discussions not being indexed">
    Discussions must be enabled on the repository for them to be indexed.

    **Solution**: Verify that GitHub Discussions is enabled in the repository settings.
  </Accordion>
</AccordionGroup>

## Security Considerations

* **Read-only access**: The connector only has read permissions
* **Repository-based permissions**: Users only see content from repositories they can access in GitHub
* **Token security**: Personal Access Tokens should be treated like passwords
* **Audit logging**: Monitor token usage in GitHub's security log

## What's Next

<CardGroup cols={3}>
  <Card title="Search Your Data" icon="magnifying-glass" href="/user-guide/search">
    Learn how to search across GitHub content
  </Card>

  <Card title="AI Assistant" icon="robot" href="/user-guide/ai-assistant">
    Ask questions about your code and issues
  </Card>

  <Card title="Add More Connectors" icon="plug" href="/connectors/overview">
    Connect additional data sources
  </Card>
</CardGroup>