> ## 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>
  Indexing uses read-only access. If you later enable GitHub OAuth actions for the AI assistant, write-capable actions require a user's own authorization and are gated by the connector's action mode.
</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**
2. Create either a classic token or a fine-grained token for the repositories you want Omni to index
3. For the simplest setup, grant the classic token the `repo` and `read:org` scopes. If you use a fine-grained token, grant read access for repository contents, issues, pull requests, discussions, metadata, and organization membership as needed.
4. Click **Generate token**
5. 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. Optionally set:
   * **API URL** for GitHub Enterprise (leave blank for github.com)
   * **Include Discussions** to index repository discussions
   * **Include Forks** to include forked repositories
   * **Read-only mode** to expose only read operations to AI tools
5. Click **Connect**
6. Click **Sync** 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 **Settings** on a source for more details and sync history.

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

### OAuth for AI Tools

The Personal Access Token handles org-wide indexing. GitHub also declares an OAuth app manifest for connector actions that need a user's own authorization. Configure the GitHub client from **Settings** → **Integrations** → **OAuth Apps** using the shared redirect URI shown on that tab. When a tool needs user authorization, the chat UI prompts the user to connect GitHub before continuing.

### Removing the Integration

1. Navigate to **Settings** → **Integrations**
2. Click **Settings** 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. Delete the existing GitHub source from **Settings** → **Integrations** → **GitHub** → **Delete Permanently**
    2. Create a new Personal Access Token and reconnect GitHub from the Integrations page
  </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>