# GitHub Repositories

Index and search GitHub repository files in Risotto

Connect your GitHub repositories to Risotto to make documentation, README files, configuration files, and other text-based content searchable through the AI assistant.

## Prerequisites

Before setting up the GitHub Repositories integration, ensure you have:

1. **GitHub Account** - Access to the GitHub repository you want to index
2. **Repository Access** - Read permissions for the target repository
3. **Personal Access Token** - GitHub token with appropriate repository permissions

## Setup Process

### Step 1: Create Personal Access Token

1. **Navigate to GitHub Token Settings**

   Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens, or visit <https://github.com/settings/personal-access-tokens>.

2. **Generate New Token**

   1. Click **Generate new token** 2. Give your token a descriptive name like
      "Risotto Repository Indexing" 3. Set an appropriate expiration period
      (recommended: 90 days or less) 4. Select **Resource owner** (your account or
      organization) 5. Under **Repository access**, choose: - **Selected
      repositories** - then select the specific repository you want to index - Or
      **All repositories** if you plan to index multiple repositories 6. Under
      **Permissions**, grant the following repository permission: - **Contents**:
      Read (to access repository files)

3. **Copy and Store Token**

   Copy the generated token immediately and store it securely. You won't be able to see it again.

   > **Warning:** Treat your personal access token like a password. Store it securely and never share it publicly.

### Step 2: Configure Integration in Risotto

1. **Open GitHub's page**

   Go to [**Settings** → **Integrations** → **GitHub**](https://dashboard.tryrisotto.com/settings/integrations/github) and open the **Knowledge** tab. In the **Repositories** section, click **Index a repository**. If you have no index yet, click **Index a repository** on the **Repositories** row. The **Index a repository** dialog opens.

2. **Configure Repository Settings**

   Enter the following required information:

   - **Personal access token**: A [vault credential](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) that holds your GitHub token. Choose it, or click **Add a vault credential** to create one.
   - **Owner**: The GitHub username or organization name (e.g., `northwind` for northwind/it-runbooks)
   - **Repository**: The repository name (e.g., `it-runbooks` for northwind/it-runbooks)
   - **Branch**: The branch to index. The field starts as `main`. If your repository's branch has another name, such as `master`, change it.

   > **Tip:** You can find the owner and repository name in the GitHub URL: `https://github.com/OWNER/REPOSITORY`

3. **Configure Optional Settings**

   Customize the indexing behavior with these optional settings:

   - **File extensions**: A comma-separated list of the file types to index. The field starts as `.md,.pdf,.txt`.
   - **Directories**: A comma-separated list of directories to include (e.g., `docs,wiki`). Leave it empty to index all directories.
   - **Department** and **Audience**: Choose who gets answers from this index. See [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

   Risotto names the index `owner/repository`.

   *Product example: The Index a repository dialog on the GitHub integration page: a token from the vault, the owner and repository, the branch, file extensions and directories, Department and Audience, and Index repository.*

   > **Warning:** The dialog warns that indexing code and binary files lowers answer quality. Keep the default extensions unless you need others.

4. **Create and Monitor Index**

   1. Click **Index repository**
   2. Watch the repository's card on the **Knowledge** tab, or the **Indexing Jobs** panel on **Knowledge > Indexes**
   3. Wait for completion before expecting search results

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds a **GitHub** index, with the same details plus an **Index name**. It is the only place to set **Profile filters**.

## Configuration Options

### Required Settings

| Field                 | Description                                              | Example                |
| --------------------- | -------------------------------------------------------- | ---------------------- |
| Personal access token | GitHub fine-grained token with Contents: Read permission | `github_pat_abc123...` |
| Owner                 | GitHub username or organization                          | `northwind`            |
| Repository            | Name of the repository                                   | `it-runbooks`          |
| Branch                | Branch to index (starts as `main`)                       | `main`, `docs`         |

### Optional Settings

| Field           | Description                   | Default         | Example         |
| --------------- | ----------------------------- | --------------- | --------------- |
| File extensions | Control indexed file types    | `.md,.pdf,.txt` | `.md,.txt,.rst` |
| Directories     | Limit to specific directories | All directories | `docs,wiki`     |

## Best Practices

### Repository Selection

- **Start with documentation-focused repositories** rather than large codebases
- **Choose stable repositories** with well-maintained documentation
- **Consider repository size** - larger repositories take longer to index

### Directory and File Filtering

- **Use directory filters** to focus on documentation folders like `docs`, `wiki`, or `guides`
- **Keep default file extensions** to avoid indexing binary files or source code
- **Test with a subset first** before indexing entire large repositories

### Branch Strategy

- **Use stable branches** like `main` or `docs` rather than development branches
- **Index documentation branches** if your team maintains separate documentation branches
- **Avoid frequently changing branches** to reduce reindexing frequency

### Security Considerations

- **Use minimal permissions** - Only grant **Contents: Read** permission
- **Use specific repository access** - Select only the repositories you need to index
- **Set short expiration periods** - Use 90 days or less and rotate regularly
- **Consider service accounts** for organization-wide integrations
- **Review indexed content** to ensure no sensitive information is included

## Managing Your GitHub Repository Index

### Monitoring Index Health

- **Check the Indexing Jobs panel** above the indexes table. A running job shows its progress there. A failed job stays there with its error message and a retry button.
- **Check the Count column** of the index to verify that the expected content was captured

### Reindexing Content

To update your index with the latest repository changes:

1. Navigate to [**Knowledge** → **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your GitHub repository index
3. Click the row's **⋮** menu (**Index actions**), then click **Reindex** to pull the latest changes
4. Monitor progress until completion

> **Note:** Risotto does not reindex GitHub repository content automatically, and you
> cannot schedule a reindex. The index keeps the content from its last run.
> Click **Reindex** after large documentation changes, or on a regular cadence,
> for example once a week. During a reindex, Risotto removes the old content
> first, so answers do not use this index until the run completes.

### Performance Optimization

- **Apply directory filters** to focus on relevant content areas
- **Review file extension filters** if indexing seems slow or includes unwanted content

### Content Verification

After indexing, test that your content is searchable:

- Use [**Knowledge** → **Playground**](https://dashboard.tryrisotto.com/knowledge/playground) to test queries
- Ask questions that should be answered using your indexed repository content
- Verify that Risotto can find and reference your documentation

## Troubleshooting

### Authentication Issues

**Problem**: Index fails with "Authentication failed" or similar error

**Solutions**:

- Verify your fine-grained personal access token is valid and not expired
- Ensure the token has **Contents: Read** permission for the target repository
- Check that the repository owner and name are spelled correctly
- Verify the token has access to the specific repository if using "Selected repositories"

### No Content Indexed

**Problem**: Index completes but shows zero or very few documents

**Solutions**:

- Verify the repository contains the expected content
- Check if directory filters are too restrictive
- Ensure the specified branch exists and contains files
- Review file extension filters to make sure they include your content types

### Slow Indexing

**Problem**: Indexing takes a very long time or times out

**Solutions**:

- Use directory filters to reduce the scope of content
- Check if the repository is very large and consider indexing in smaller chunks
- Contact support if indexing consistently fails for appropriately sized repositories

### Permission Errors

**Problem**: "Access denied" or "Repository not found" errors

**Solutions**:

- Verify you have read access to the repository
- For private repositories, ensure your token has **Contents: Read** permission
- For organization repositories, check that the organization has approved fine-grained tokens
- Confirm the repository owner and name are correct
- Verify the specific repository is included in your token's repository access scope

## Support and Next Steps

After setting up your GitHub repository index:

1. **Test the integration** using [**Knowledge** → **Playground**](https://dashboard.tryrisotto.com/knowledge/playground) to verify your content is searchable
2. **Ask Risotto questions** about your indexed documentation in Slack
3. **Monitor answer quality** and adjust filters if needed
4. **Set up regular reindexing** to keep content current
5. **Expand gradually** by adding more repositories as needed

For additional help with GitHub integrations, contact support at <support@tryrisotto.com>.

Source: https://www.tryrisotto.com/docs/integrations/knowledge/github-repositories
