Docs

Integrations / Knowledge

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

Step 2: Configure Integration in Risotto

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

  2. 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., 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.
  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.

    Risotto names the index owner/repository.

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

FieldDescriptionExample
Personal access tokenGitHub fine-grained token with Contents: Read permissiongithub_pat_abc123...
OwnerGitHub username or organizationnorthwind
RepositoryName of the repositoryit-runbooks
BranchBranch to index (starts as main)main, docs

Optional Settings

FieldDescriptionDefaultExample
File extensionsControl indexed file types.md,.pdf,.txt.md,.txt,.rst
DirectoriesLimit to specific directoriesAll directoriesdocs,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
  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

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:

  1. Test the integration using 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.

Something wrong or missing? Report an issue · View as Markdown