How to Manually Configure a GitHub Token for Private Repository Access in Agent Reach

Store your GitHub Personal Access Token in ~/.agent-reach/config.yaml under the github_token key using the CLI command agent-reach configure github-token <TOKEN>, or set the GITHUB_TOKEN environment variable for automatic detection.

Agent Reach requires authentication to access private GitHub repositories. According to the Panniantong/Agent-Reach source code, the tool centralizes credentials in a YAML configuration file and supports multiple configuration methods including CLI commands, manual file editing, and environment variables.

Create a GitHub Personal Access Token

Before configuring Agent Reach, generate a token with appropriate permissions. Navigate to https://github.com/settings/tokens and create a new token with a descriptive name. You do not need to assign any specific scopes for basic private repository access; a token with no scope works for reading private repositories.

Copy the generated token immediately, as GitHub displays it only once during creation.

Configure the Token in Agent Reach

The configuration system is implemented in agent_reach/config.py, where the Config class manages persistence and retrieval of the github_token value.

Method 1: CLI Configuration (Recommended)

Use the configure subcommand to securely store the token. The CLI parser in agent_reach/cli.py (lines 1101-1103) handles the github-token argument and calls Config.set("github_token", value).

agent-reach configure github-token ghp_YourTokenHere

The command writes to ~/.agent-reach/config.yaml and prints "✅ GitHub token configured!" upon success. The Config.save method creates the file with 0600 permissions (owner read/write only) to prevent unauthorized access.

Method 2: Manual Configuration File Editing

Edit the YAML file directly at ~/.agent-reach/config.yaml:

github_token: ghp_YourTokenHere

The Config.save method (lines 49-66 in agent_reach/config.py) ensures the file maintains secure permissions when modified.

Method 3: Environment Variable

Set the GITHUB_TOKEN environment variable. The Config.get method (lines 69-77 in agent_reach/config.py) checks for the uppercase environment variable as a fallback when the config file value is absent.

export GITHUB_TOKEN=ghp_YourTokenHere

This method is useful for CI/CD pipelines or temporary configurations where you do not want to persist credentials to disk.

Verify the Configuration

Run the health check to confirm authentication:

agent-reach doctor

The GitHubChannel.check method (lines 19-43 in agent_reach/channels/github.py) validates the token against the GitHub API. A successful check reports ok or warn (if the gh CLI is missing but the token remains valid for direct API calls).

Programmatic Access

Access the token in Python using the Config class:

from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")  # Returns the token string or None

The Config.get method first checks the in-memory dictionary, then falls back to the GITHUB_TOKEN environment variable if the configuration file does not contain the key.

Summary

• Agent Reach stores GitHub tokens in ~/.agent-reach/config.yaml under the github_token key
• Use agent-reach configure github-token <TOKEN> for secure CLI-based configuration with automatic 0600 file permissions
• The Config.get method in agent_reach/config.py checks for the GITHUB_TOKEN environment variable (uppercase) as a fallback
• Verify authentication using agent-reach doctor, which invokes GitHubChannel.check in agent_reach/channels/github.py
• No specific GitHub scopes are required for the token to access private repositories

Frequently Asked Questions

Where does Agent Reach store the GitHub token?

Agent Reach stores the token in ~/.agent-reach/config.yaml as the github_token key. The Config.save method in agent_reach/config.py (lines 49-66) creates this file with 0600 permissions, ensuring only the file owner can read or write the credential.

Can I use an environment variable instead of the config file?

Yes. The Config.get method (lines 69-77 in agent_reach/config.py) checks for the GITHUB_TOKEN environment variable (uppercase) if the value is not found in the configuration file. This allows temporary or CI/CD-based authentication without modifying persistent files.

What permissions does my GitHub token need?

No specific scopes are required for basic private repository access. When generating the token at https://github.com/settings/tokens, you can leave all scopes unchecked. The token only needs standard read permissions to access repository contents and metadata through the GitHub API.

How do I verify that my token is working correctly?

Run agent-reach doctor to execute the health check. The GitHubChannel.check method in agent_reach/channels/github.py (lines 19-43) validates the token against the GitHub API. If the token is valid, the check reports ok or warn if the gh CLI is missing but the token remains functional for direct API calls.

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