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

Configure your GitHub personal access token in Agent Reach by running agent-reach configure github-token <TOKEN>, which securely stores the credential in ~/.agent-reach/config.yaml with 0600 permissions for private repository access.

Agent Reach requires authentication to read private repositories through the GitHub API. This guide explains how to securely store a personal access token using the CLI configuration commands and how the credential is managed internally by the Config class in the Panniantong/Agent-Reach repository.

Where Agent Reach Stores Authentication Credentials

Agent Reach maintains user-specific settings in a YAML configuration file located at ~/.agent-reach/config.yaml. The github_token key holds the personal access token used for authenticating with private GitHub repositories.

The Config class in agent_reach/config.py handles persistence through the set method (lines 27-33), which writes values to this file. When saving credentials, the Config.save method (lines 49-66) sets file permissions to 0600, ensuring only the file owner can read or write the token.

Step-by-Step Configuration Guide

Generate a Personal Access Token on GitHub

Create a token with default permissions that grants read access to private repositories:

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. Leave all scopes unchecked—Agent Reach requires no special scopes for repository reading
5. Click "Generate token" and copy the value immediately

Store the Token Using the CLI

Use the configure sub-command with the github-token argument to persist the token:

agent-reach configure github-token ghp_your_token_here

The CLI entry point in agent_reach/cli.py (lines 1101-1103) parses this argument and calls config.set("github_token", value), writing the token to your configuration file. The command outputs "✅ GitHub token configured!" upon successful storage.

Verify the Configuration

Confirm the token was saved correctly:

cat ~/.agent-reach/config.yaml

You should see the github_token entry:

github_token: ghp_your_token_here

Run the health check to validate authentication:

agent-reach doctor

The GitHubChannel.check method in agent_reach/channels/github.py (lines 19-43) verifies the token works with the GitHub API, reporting ok if authentication succeeds.

How the Token Is Used Internally

Agent Reach retrieves the token through the Config.get method (lines 69-77 in agent_reach/config.py), which implements a fallback hierarchy:

1. In-memory cache: Checks the loaded configuration dictionary first
2. Environment variable: Falls back to GITHUB_TOKEN (uppercase) if not found in config
3. Return None: If neither source provides the token

The GitHubChannel class uses this token to authenticate API requests, either through the authenticated gh CLI when available or via direct API calls using the stored credential.

Configuration Code Examples

Set token via CLI (recommended):

agent-reach configure github-token ghp_xxxxxxxxxxxxxxxxxxxx

Read token programmatically:

from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")
print(f"Token configured: {token[:8]}...")

Manual configuration (advanced):

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

github_token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ensure the file maintains 0600 permissions after manual editing:

chmod 600 ~/.agent-reach/config.yaml

Summary

• Agent Reach stores GitHub tokens in ~/.agent-reach/config.yaml under the github_token key
• Use agent-reach configure github-token <TOKEN> to set credentials securely via the CLI
• The configuration file uses 0600 permissions to protect the token from unauthorized access
• The Config.get method checks the config file first, then falls back to the GITHUB_TOKEN environment variable
• Verify authentication works by running agent-reach doctor to execute the GitHubChannel.check health verification

Frequently Asked Questions

Where does Agent Reach store the GitHub personal access token?

Agent Reach stores the token in the YAML file at ~/.agent-reach/config.yaml under the github_token key. The Config.save method in agent_reach/config.py creates this file with 0600 permissions (read/write for owner only) to ensure the credential remains private and inaccessible to other system users.

Can I use an environment variable instead of the configuration 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 allows temporary or CI/CD-based authentication without persisting credentials to disk.

What GitHub scopes or permissions does the token require?

Agent Reach requires no special scopes for accessing private repositories. When generating the token at https://github.com/settings/tokens, you can leave all scope checkboxes unchecked. The default "no scope" token provides sufficient permissions for the read and search operations performed by the GitHubChannel class in agent_reach/channels/github.py.

How do I verify that my GitHub token is configured correctly?

Run agent-reach doctor to execute the health check system. The GitHubChannel.check method (lines 19-43 in agent_reach/channels/github.py) validates the token by attempting to authenticate with the GitHub API. A successful check returns ok, while configuration issues result in warn or error states that indicate whether the token is invalid, missing, or the gh CLI is unavailable.

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