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:
- GitHub Account - Access to the GitHub repository you want to index
- Repository Access - Read permissions for the target repository
- Personal Access Token - GitHub token with appropriate repository permissions
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 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)
Copy and Store Token
Copy the generated token immediately and store it securely. You won't be able to see it again.
Step 2: Configure Integration in Risotto
Open GitHub's page
Go to 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.
Configure Repository 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-runbooks) - Repository: The repository name (e.g.,
it-runbooksfor northwind/it-runbooks) - Branch: The branch to index. The field starts as
main. If your repository's branch has another name, such asmaster, change it.
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.
Risotto names the index
owner/repository.- File extensions: A comma-separated list of the file types to index. The field starts as
Create and Monitor Index
- Click Index repository
- Watch the repository'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 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, orguides - 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
mainordocsrather 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:
- Navigate to Knowledge → Indexes
- Find your GitHub repository index
- Click the row's ⋮ menu (Index actions), then click Reindex to pull the latest changes
- Monitor progress until completion
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 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:
- Test the integration using Knowledge → Playground to verify your content is searchable
- Ask Risotto questions about your indexed documentation in Slack
- Monitor answer quality and adjust filters if needed
- Set up regular reindexing to keep content current
- Expand gradually by adding more repositories as needed
For additional help with GitHub integrations, contact support at support@tryrisotto.com.
Something wrong or missing? Report an issue · View as Markdown