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.
Prerequisites
Before setting up the GitHub Wikis integration, ensure you have:
- GitHub Account - Access to the GitHub repository with an enabled wiki
- Wiki Access - Read permissions for the target repository and its wiki
- Personal Access Token - GitHub token with appropriate repository permissions
- Active Wiki - The repository must have wiki functionality enabled with existing content
Setup Process
Step 1: Create Personal Access Token
Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens, or visit https://github.com/settings/personal-access-tokens.
Generate New Token
- 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)
- 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)
Copy and Store Token
Copy the generated token immediately and store it securely. You won't be able to see it again.
Step 2: Verify Wiki Exists
Check Wiki Tab
Navigate to your GitHub repository and verify that:
- The Wiki tab is visible in the repository navigation
- The wiki contains content (at least a home page)
- You have read access to the wiki content
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.
Step 3: Configure Integration in Risotto
Open GitHub's page
Go to 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 and pick GitHub Wiki, or add a repository first.
Configure Wiki Settings
Enter the following required information:
- Personal access token: A vault credential 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.,
northwindfor northwind/it-handbook) - Repository: The repository name that contains the wiki (e.g.,
it-handbookfor northwind/it-handbook) - Department and Audience: Choose who gets answers from this index. See Indexes.
Create and Monitor Index
- Click Index wiki
- Watch the wiki's card on the Knowledge tab, or the Indexing Jobs panel on Knowledge > Indexes
- 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:
- Navigate to Knowledge → Indexes
- Find your GitHub wiki index
- Click the row's ⋮ menu (Index actions), then click Reindex to pull the latest changes
- Monitor progress until completion
Content Verification
After indexing, test that your wiki content is searchable:
- Use 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
.mdextension (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:
- Test the integration using Knowledge → Playground to verify your content is searchable
- Ask Risotto questions about your wiki content in Slack
- Monitor answer quality and update wiki content if needed
- Set up regular reindexing to keep content current
- 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.
Something wrong or missing? Report an issue · View as Markdown