How to Configure a GitHub Token for Accessing Private Repositories with Agent Reach

Agent Reach reads a GitHub token from three sources: the config file, the GH_TOKEN environment variable, or the GITHUB_TOKEN environment variable, enabling seamless authentication for private repositories.

Agent Reach is an open-source tool that enables programmatic interaction with code repositories. To access private GitHub repositories, you must configure a GitHub personal access token. This guide explains exactly how Agent Reach handles token configuration based on the source code in Panniantong/Agent-Reach.

Where Agent Reach Looks for Your Token

The token resolution follows a clear priority order in agent_reach/channels/github.py:

1. GH_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. github_token key in ~/.agent-reach/config.yaml

The GitHubChannel.check() method implements this fallback chain at lines 84-92:

# From agent_reach/channels/github.py

def check(self):
    # First check environment variables

    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
    if not token:
        # Fall back to config file

        token = self.config.get("github_token")
    return token is not None

When any of these sources contains a valid token, the GitHubChannel authenticates through the gh CLI without prompting the user.

Method 1: Configure via CLI Command

The most direct approach uses the built-in configuration command. In agent_reach/cli.py (lines 1312-1315), the configure github-token subcommand persists your token:

# Generate a personal access token on GitHub with 'repo' scope first

agent-reach configure github-token ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

The CLI writes to ~/.agent-reach/config.yaml through Config.set(). The Config class in agent_reach/config.py (lines 1110-1112) registers "github_token" as a required key for the github_token feature, ensuring validation on access.

Verify the configuration:

agent-reach doctor

# Expected output: GitHub channel reports "configured"

Method 2: Use Environment Variables

For CI/CD pipelines or temporary configurations, export either variable:

export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Alternative:

export GH_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

With the environment variable set, Agent Reach picks up the token automatically—no config file needed:

agent-reach doctor   # → GitHub channel reports "configured"

agent-reach read https://github.com/your-org/private-repo/blob/main/README.md

This approach skips disk entirely, which is ideal for ephemeral environments.

Method 3: Programmatic Configuration

For embedded usage or custom tooling, interact with the Config class directly:

from agent_reach.config import Config

cfg = Config()
cfg.set("github_token", "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX")

# Verify storage

print(cfg.get("github_token"))  # → ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

The Config class handles atomic writes with owner-only permissions to prevent symlink attacks, as implemented in agent_reach/config.py.

Security and Storage Details

Aspect	Implementation Detail
File permissions	Config file written with owner-only access
Write safety	Atomic file operations prevent partial writes
Environment precedence	GH_TOKEN > GITHUB_TOKEN > config file
Doctor limitations	Verifies token existence, not validity—no gh auth status call to avoid device-id file creation

Complete Workflow Example

# Step 1: Generate token at https://github.com/settings/tokens (select 'repo' scope)

# Step 2: Configure Agent Reach

agent-reach configure github-token ghp_xxxxxxxxxxxxxxxxxxxx

# Step 3: Verify

agent-reach doctor

# Step 4: Access private repository content

agent-reach read https://github.com/mycompany/internal-api/blob/main/src/main.py

Troubleshooting Private Repository Access

If private repositories remain inaccessible:

• Confirm token has repo scope (or appropriate fine-grained permissions)
• Check agent-reach doctor reports GitHub channel as configured
• Verify no conflicting GH_TOKEN/GITHUB_TOKEN values override your config
• Validate token expiration date in GitHub settings

Summary

• Three valid sources: GH_TOKEN, GITHUB_TOKEN, or config file via agent-reach configure github-token
• CLI convenience: agent-reach configure github-token <TOKEN> persists to ~/.agent-reach/config.yaml
• Environment flexibility: Shell variables work immediately without config file modification
• Implementation locations: cli.py (command handling), config.py (storage), channels/github.py (runtime resolution)

Frequently Asked Questions

What GitHub token permissions does Agent Reach require?

Agent Reach requires the repo scope for classic tokens, or equivalent repository read access for fine-grained personal access tokens. The token must grant access to the specific private repositories you intend to read.

Can I use a GitHub App installation token instead of a personal access token?

The current implementation in agent_reach/channels/github.py expects a personal access token format. While the underlying gh CLI supports GitHub Apps, Agent Reach's token validation assumes direct personal access token strings.

Why does agent-reach doctor succeed but my private repo access fails?

The doctor command only checks that a token exists in configuration or environment—it does not validate the token against GitHub's API. Actual repository access failure typically indicates insufficient token scopes, repository permissions, or token expiration.

How do I remove a stored GitHub token?

Delete the github_token key from ~/.agent-reach/config.yaml or unset the GH_TOKEN/GITHUB_TOKEN environment variables. There is currently no dedicated CLI command for token removal.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}