GitHubRepoViewer

Browse and read files from a GitHub repository—designed for AI agents that need to explore repository contents before editing or summarizing code.

Key Features

• Navigates both files and directories in any GitHub repository.
• For directories, returns one Document per item with the path and type in metadata.
• For files, returns a single Document containing the full file content.
• Enforces a configurable maximum file size to prevent oversized payloads.
• Accepts a default repository and branch at initialization; both can be overridden at run time.
• Works with public repositories without a token; optionally resolves a GITHUB_TOKEN secret for private repos or higher rate limits.
• Also available as GitHubRepoViewerTool for use with Haystack agents.

Configuration

1. Optionally, store your GitHub personal access token as a secret named GITHUB_TOKEN. For instructions, see Create Secrets.
2. Drag the GitHubRepoViewer component onto the canvas from the Component Library.
3. Click on the component to open the configuration panel.
4. Set repo to the default repository in owner/repo format and branch to the target branch.

Connections

GitHubRepoViewer receives a path (the file or directory path within the repository) and optionally a repo and branch override. It outputs a documents list. Connect the output to a prompt builder, DocumentJoiner, or any component that accepts a list of documents.

Source Code

To check this component's source code, open repo_viewer.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  GitHubRepoViewer:
    type: haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer
    init_parameters:
      github_token:
        type: env_var
        env_vars:
        - GITHUB_TOKEN
        strict: false
      repo: owner/my-repo
      branch: main
      max_file_size: 1000000
      raise_on_failure: true

Using the Component in a Pipeline

This example shows a pipeline that reads a file from a repository and uses an LLM to summarize it.

# haystack-pipeline

components:
  repo_viewer:
    type: haystack_integrations.components.connectors.github.repo_viewer.GitHubRepoViewer
    init_parameters:
      github_token:
        type: env_var
        env_vars:
        - GITHUB_TOKEN
        strict: false
      repo: owner/my-repo
      branch: main

  prompt_builder:
    type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      template:
      - role: user
        content: "Summarize the following file:\n\n{{ documents[0].content }}"
      required_variables:
      - documents

  llm:
    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
    init_parameters:
      model: gpt-4o-mini

connections:
- sender: repo_viewer.documents
  receiver: prompt_builder.documents
- sender: prompt_builder.prompt
  receiver: llm.messages

inputs:
  query:
  - repo_viewer.path

outputs:
  replies: llm.replies

max_runs_per_component: 100

metadata: {}

Parameters

Inputs

Parameter	Type	Default	Description
path	str		Path to a file or directory within the repository (for example, src/ or README.md).
repo	Optional[str]	None	Repository in owner/repo format. Overrides the default set at initialization.
branch	Optional[str]	None	Git reference (branch, tag, or commit SHA). Overrides the default set at initialization.

Outputs

Parameter	Type	Description
documents	List[Document]	For a directory: one Document per item with the item name as content and path and type in metadata. For a file: one Document with the file content and path, size, and URL in metadata.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
github_token	Optional[Secret]	None	GitHub personal access token used for API authentication. Not required for public repositories.
raise_on_failure	bool	True	If True, raises an exception on errors. If False, returns an error document.
max_file_size	int	1000000	Maximum file size in bytes to fetch. Files larger than this limit produce an error.
repo	Optional[str]	None	Default repository in owner/repo format.
branch	str	main	Default Git reference (branch, tag, or commit SHA) to use.

Related Information

• GitHubFileEditor
• GitHubIssueViewer
• Pipeline Components