# GitHub Wikis

Index and search GitHub wiki pages in Risotto

Connect your GitHub wikis to Risotto to make wiki documentation and knowledge base articles searchable through the AI assistant.

> **Note:** GitHub maintains a specialized wiki repository for every GitHub repository
> that has a wiki enabled. This integration specifically targets those wiki
> repositories and only indexes markdown content.

## Prerequisites

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

1. **GitHub Account** - Access to the GitHub repository with an enabled wiki
2. **Wiki Access** - Read permissions for the target repository and its wiki
3. **Personal Access Token** - GitHub token with appropriate repository permissions
4. **Active Wiki** - The repository must have wiki functionality enabled with existing content

## 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 Wiki Indexing" 3. Set an appropriate expiration period (recommended:
      90 days or less) 4. Select **Resource owner** (your account or organization)
   2. Under **Repository access**, choose: - **Selected repositories** - then
      select the specific repository whose wiki you want to index - Or **All
      repositories** if you plan to index multiple repository wikis 6. Under
      **Permissions**, grant the following repository permission: - **Contents**:
      Read (to access wiki repository content)

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: Verify Wiki Exists

1. **Check Wiki Tab**

   Navigate to your GitHub repository and verify that:

   1. The **Wiki** tab is visible in the repository navigation
   2. The wiki contains content (at least a home page)
   3. You have read access to the wiki content

2. **Test Wiki Access**

   Visit the wiki by clicking the **Wiki** tab in your repository to ensure it loads properly and contains the content you want to index.

   > **Tip:** If you don't see a Wiki tab, the repository owner needs to enable wiki functionality in the repository settings under **Features**.

### Step 3: 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 **Wikis** section, click **Index a wiki**. The **Index a wiki** dialog opens.

   When nothing on the GitHub page is connected yet, the page shows a setup row that offers only **Index a repository**. To index only a wiki, use **Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) and pick **GitHub Wiki**, or add a repository first.

2. **Configure Wiki 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-handbook)
   - **Repository**: The repository name that contains the wiki (e.g., `it-handbook` for northwind/it-handbook)
   - **Department** and **Audience**: Choose who gets answers from this index. See [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

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

   > **Note:** Unlike repository indexing, wiki indexing doesn't require branch or directory configuration since GitHub wikis have a standardized structure.

3. **Create and Monitor Index**

   1. Click **Index wiki**
   2. Watch the wiki'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** adds a **GitHub Wiki** 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 containing the wiki               | `it-handbook`          |

### Automatic Behavior

GitHub Wiki indexing automatically:

- **Indexes only markdown files** (`.md`) from the wiki repository
- **Follows wiki structure** including the home page and all wiki pages
- **Preserves wiki organization** with proper page titles and relationships
- **Updates page history** when reindexing to capture latest changes

## Best Practices

### Wiki Organization

- **Use clear page titles** that accurately describe the content
- **Organize with a logical structure** using the wiki's built-in navigation
- **Create a comprehensive home page** that serves as an entry point
- **Link related pages** to improve discoverability

### Content Quality

- **Write descriptive headings** to help Risotto understand page structure
- **Use consistent formatting** across all wiki pages
- **Keep content current** and remove outdated information
- **Include relevant keywords** that users might search for

### Access Management

- **Use minimal permissions** - Only grant **Contents: Read** permission
- **Use specific repository access** - Select only the repositories whose wikis you need to index
- **Set short expiration periods** - Use 90 days or less and rotate regularly
- **Consider service accounts** for organization-wide wiki integrations
- **Document token usage** for your team's security records

### Wiki Maintenance

- **Review content regularly** to ensure accuracy and relevance
- **Archive obsolete pages** rather than leaving outdated information
- **Use consistent naming** for wiki pages to improve searchability
- **Test Risotto responses** after major wiki updates

## Managing Your GitHub Wiki 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 all wiki pages were captured
- **Test search functionality** by asking Risotto questions about wiki content

### Reindexing Content

To update your index with the latest wiki changes:

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

> **Tip:** Reindex your wiki whenever significant content changes are made. Consider
> monthly reindexing for actively maintained wikis.

### Content Verification

After indexing, test that your wiki content is searchable:

- Use [**Knowledge** → **Playground**](https://dashboard.tryrisotto.com/knowledge/playground) to test queries
- Ask questions that should be answered using your indexed wiki content
- Verify that Risotto can find and reference your wiki pages
- Check that links and references work properly in responses

## 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"
- Confirm you have access to both the repository and its wiki

### Wiki Not Found

**Problem**: Error message indicating wiki doesn't exist or can't be accessed

**Solutions**:

- Verify the repository has wiki functionality enabled
- Check that the wiki contains at least one page (usually the Home page)
- Ensure your token has **Contents: Read** permission for the repository containing the wiki
- For organization repositories, verify the organization has approved fine-grained tokens
- Confirm the repository owner and name are correct

### No Content Indexed

**Problem**: Index completes but shows zero documents

**Solutions**:

- Verify the wiki actually contains markdown content
- Check if the wiki pages are published and accessible
- Ensure wiki pages have `.md` extension (GitHub wikis use markdown by default)
- Try accessing the wiki manually to confirm content exists

### Incomplete Indexing

**Problem**: Only some wiki pages are indexed

**Solutions**:

- Wait for indexing to fully complete (large wikis may take time)
- Check if some pages have access restrictions
- Verify all pages are properly formatted markdown
- Reindex if the process was interrupted

## Support and Next Steps

After setting up your GitHub wiki 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 wiki content in Slack
3. **Monitor answer quality** and update wiki content if needed
4. **Set up regular reindexing** to keep content current
5. **Train your team** on how to maintain wiki content for better AI responses

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

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