How to Configure Private GitHub Access in Agent Reach

Agent Reach authenticates to private GitHub repositories using a Personal Access Token (PAT) stored in ~/.agent-reach/config.yaml or via the GITHUB_TOKEN environment variable, enabling the GitHub CLI (gh) to access private repos on your behalf.

To enable AI agents to interact with private source code, Panniantong/Agent-Reach requires explicit authentication credentials. Configuring private GitHub access in Agent Reach involves supplying a GitHub Personal Access Token that the tool persists securely and passes to the underlying GitHub CLI.

Understanding the Authentication Flow

Agent Reach does not implement its own GitHub API client. Instead, it wraps the GitHub CLI (gh) and manages authentication tokens on your behalf. The Config class in agent_reach/config.py defines a required feature called github_token (line 29), which the system checks before executing any repository operations.

When properly configured, Agent Reach writes your token to its local YAML configuration file and ensures the gh binary uses these credentials when cloning, reading, or analyzing private repositories.

Step-by-Step Configuration

Generate a GitHub Personal Access Token

Before configuring Agent Reach, create a token with appropriate permissions:

1. Navigate to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) or Fine-grained tokens.
2. Enable the repo scope for full control of private repositories.
3. Add read:org if you need to access organization-level repository information.
4. Copy the generated token (format: ghp_...).

Store the Token via Agent Reach CLI

Use the built-in configuration command to persist the token:

agent-reach configure github-token ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This command invokes config.set("github_token", value) in agent_reach/cli.py (line 1123), writing the credential to ~/.agent-reach/config.yaml. The token is stored with standard filesystem permissions.

Verify Private Repository Access

Confirm the GitHub channel is active using the diagnostic command:

agent-reach doctor

For JSON output inspection:

agent-reach doctor --json | jq '.github'

# Expected output: { "status": "ok", "details": "gh CLI + token" }

With a valid token, gh repo view owner/private-repo executes successfully through Agent Reach.

Alternative: Environment Variable Authentication

If you prefer not to write credentials to disk, Agent Reach supports runtime authentication via environment variables. The Config.get() method checks for the GITHUB_TOKEN environment variable after inspecting the configuration file.

Set the variable in your shell:

export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
agent-reach doctor  # Detects token via env var without file persistence

This approach is ideal for CI/CD pipelines or temporary access scenarios where you want to avoid persisting secrets in ~/.agent-reach/config.yaml.

Technical Implementation Details

The authentication system relies on three core components:

• agent_reach/config.py: Implements the Config class that defines the github_token requirement and handles YAML persistence.
• agent_reach/cli.py: Provides the configure github-token interface that writes to the configuration object.
• ~/.agent-reach/config.yaml: Stores the actual token value (masked in CLI output).

When the doctor command reports the GitHub channel as ready, any subsequent agent-reach invocation that calls gh (such as gh issue list or gh repo view) automatically inherits the stored credentials.

Summary

• Agent Reach uses the GitHub CLI (gh) for all repository operations, requiring a Personal Access Token for private repos.
• Store tokens via agent-reach configure github-token <token> to write to ~/.agent-reach/config.yaml as implemented in agent_reach/cli.py.
• Minimum required scope is repo for private repository access.
• Environment variable fallback allows using GITHUB_TOKEN instead of file-based configuration.
• Verify setup with agent-reach doctor to ensure the GitHub channel status reports "ok".

Frequently Asked Questions

What GitHub token scopes are required for Agent Reach?

The token must include the repo scope to grant full control of private repositories. If your workflows involve organization-level data or team mentions, add the read:org scope. Fine-grained personal access tokens require read access to repository contents and metadata.

Is it safe to store my GitHub token in Agent Reach's configuration file?

Agent Reach stores the token in ~/.agent-reach/config.yaml with standard filesystem permissions. While this is convenient for persistent access, users with strict security requirements should use the GITHUB_TOKEN environment variable method instead, which leaves no persistent credential on disk between sessions.

Why does Agent Reach use the GitHub CLI instead of direct API calls?

Agent Reach wraps the GitHub CLI (gh) to leverage its built-in authentication handling, caching, and error management. This design, implemented in agent_reach/config.py and agent_reach/cli.py, ensures compatibility with existing GitHub authentication methods while minimizing credential handling complexity in the Agent Reach codebase.

How do I troubleshoot "GitHub channel not ready" errors?

Run agent-reach doctor to diagnose connectivity. If the GitHub check fails, verify that your token is valid (not expired), has the repo scope, and is either stored in the config file via agent-reach configure github-token or exported as GITHUB_TOKEN. Ensure the gh CLI is installed and accessible in your system PATH.

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