How to Configure GitHub Tokens for Private Repository Access in Agent Reach

Agent Reach stores GitHub personal access tokens in ~/.agent-reach/config.yaml under the github_token key, which can be set via the CLI command agent-reach configure github-token <TOKEN> or the GITHUB_TOKEN environment variable.

To enable Agent Reach to access private GitHub repositories, you must provide a valid authentication token. This configuration step is essential for the GitHubChannel to authenticate API requests and perform repository operations. The following guide covers the complete setup process based on the actual implementation in the Panniantong/Agent-Reach repository.

Setting Up the GitHub Personal Access Token

Creating a Token on GitHub

Before configuring Agent Reach, generate a Personal Access Token (PAT) from your GitHub account settings.

1. Navigate to https://github.com/settings/tokens.
2. Click "Generate new token (classic)".
3. Provide a descriptive name (e.g., "Agent-Reach-Access").
4. Set an expiration date according to your security policy.
5. Copy the generated token immediately (it is displayed only once).

Required Permissions (Scopes)

For private repository access in Agent Reach, you do not need to select any specific scopes. The default "no scope" token provides sufficient permissions for reading private repositories. This minimal permission approach follows the principle of least privilege while allowing the GitHubChannel to perform necessary read and search operations.

Configuring Agent Reach with Your Token

Using the CLI (Recommended)

The most secure method to store your token is through the Agent Reach CLI, which writes the value to the configuration file with proper file permissions (0600).

In agent_reach/cli.py (lines 1101-1103), the argument parser handles the github-token sub-command and invokes config.set("github_token", value):

agent-reach configure github-token <YOUR_TOKEN>

Upon successful execution, the CLI prints "✅ GitHub token configured!" and saves the value to ~/.agent-reach/config.yaml. The Config.save method (lines 49-66 in agent_reach/config.py) ensures the file is created with read/write permissions for the owner only, preventing unauthorized access.

Environment Variable Fallback

Agent Reach supports an environment variable fallback mechanism. If the github_token key is not set in the configuration file, the Config.get method (lines 69-77 in agent_reach/config.py) automatically checks for the GITHUB_TOKEN environment variable (uppercase):

export GITHUB_TOKEN=ghp_your_token_here

This fallback is useful for CI/CD pipelines or temporary configurations where you prefer not to write credentials to disk.

Manual Configuration (Advanced)

You can directly edit the YAML configuration file, though this is discouraged for production environments due to the risk of leaving tokens in shell history or clipboard.

Edit ~/.agent-reach/config.yaml:

github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

Ensure the file maintains 0600 permissions after editing to protect the sensitive credential.

How Agent Reach Reads the Token

The configuration system uses a centralized Config class defined in agent_reach/config.py. When the GitHubChannel needs to authenticate, it retrieves the token via Config.get("github_token"), which implements the following resolution order:

1. In-memory dictionary: Values set during the current session
2. Configuration file: The github_token entry in ~/.agent-reach/config.yaml
3. Environment variable: GITHUB_TOKEN (converted to uppercase automatically)

The Config.set method (lines 27-33) handles the initial storage when using the CLI, while the Config.get method (lines 69-77) manages the retrieval logic with fallback support.

Verifying the Configuration

After configuring your token, verify connectivity using the built-in health check. The GitHubChannel.check method (lines 19-43 in agent_reach/channels/github.py) validates that the token can authenticate with the GitHub API.

Run the diagnostic command:

agent-reach doctor

The output includes a GitHub section indicating the status:

• ok: The token is valid and the gh CLI is installed
• warn: The token is valid but the gh CLI is missing (Agent Reach will use direct API calls instead)
• error: The token is invalid or missing

Summary

• Storage location: ~/.agent-reach/config.yaml under the github_token key
• CLI command: agent-reach configure github-token <TOKEN> writes the value securely with 0600 permissions
• Environment fallback: GITHUB_TOKEN is checked if the config file entry is absent
• Required permissions: No special scopes required for private repository read access
• Verification: Use agent-reach doctor to confirm the GitHubChannel can authenticate
• Source files: Configuration logic in agent_reach/config.py (lines 27-77), CLI handling in agent_reach/cli.py (lines 1101-1103), and channel implementation in agent_reach/channels/github.py (lines 19-43)

Frequently Asked Questions

Where does Agent Reach store the GitHub token?

Agent Reach stores the token in a YAML configuration file located at ~/.agent-reach/config.yaml under the key github_token. According to the source code in agent_reach/config.py, the Config.save method 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 in agent_reach/config.py (lines 69-77) implements a fallback mechanism that checks for the GITHUB_TOKEN environment variable (uppercase) if the github_token key is not present in the configuration file. This is useful for ephemeral environments or when you want to avoid writing secrets to disk.

What scopes does the GitHub token need for private repositories?

Agent Reach requires no specific scopes for accessing private repositories. A classic Personal Access Token with the default "no scope" setting provides sufficient permissions for reading repository contents and performing search operations. You do not need to enable repo scope unless you intend to perform write operations.

How do I verify my GitHub token is working with Agent Reach?

Run agent-reach doctor to execute the health check implemented in agent_reach/channels/github.py. The GitHubChannel.check method (lines 19-43) validates the token against the GitHub API. If the token is valid, the output will show either ok (if the gh CLI is installed) or warn (if using direct API calls without the CLI).

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