How to Configure GitHub Token for Private Repos in Agent-Reach

Store your GitHub Personal Access Token using agent-reach configure github-token <TOKEN> to enable authenticated access to private repositories.

Agent-Reach stores user-specific settings in a YAML configuration file located at ~/.agent-reach/config.yaml. The github_token key within this file controls access to private GitHub repositories. This guide explains how to set up this token using the CLI or manual configuration, based on the actual source code implementation in the Panniantong/Agent-Reach repository.

Storing the GitHub Token

You have two methods for configuring your GitHub token: using the interactive CLI (recommended) or editing the configuration file directly.

Using the CLI (Recommended)

The configure subcommand in agent_reach/cli.py (lines 1101-1103) handles token storage securely. Run the following command and replace <YOUR_TOKEN> with your GitHub Personal Access Token:

agent-reach configure github-token ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The CLI calls config.set("github_token", value) internally, which writes the token to ~/.agent-reach/config.yaml. After execution, you will see the confirmation: "✅ GitHub token configured!"

Manual Configuration (Advanced)

You can directly edit the configuration file at ~/.agent-reach/config.yaml. The file uses YAML format with the github_token key:

github_token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

According to the Config.save method in agent_reach/config.py (lines 49-66), this file is created with permissions 0600 (read/write for owner only), ensuring your token remains private.

How the Configuration Works Internally

Understanding the internal mechanics helps with troubleshooting and advanced use cases.

The Config Class

The Config class in agent_reach/config.py manages the github_token key. When you run the configure command, the Config.set method (lines 27-33) updates the in-memory configuration and triggers a save to disk.

Environment Variable Fallback

If the token is not found in the configuration file, Config.get (lines 69-77) automatically checks for an environment variable named GITHUB_TOKEN (uppercase). This allows temporary overrides without modifying the config file:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
agent-reach doctor

GitHub Channel Integration

The GitHubChannel class in agent_reach/channels/github.py (lines 19-43) uses this token for authentication. During the health check (GitHubChannel.check), the channel validates the token against the GitHub API, either through the authenticated gh CLI or direct API calls using the stored token.

Verifying Private Repository Access

After configuration, verify that Agent-Reach can communicate with private repositories.

Using the Doctor Command

Run the built-in diagnostic tool to confirm your token works:

agent-reach doctor

The output includes a GitHub section. A valid token shows ok, while a missing gh CLI but valid token shows warn (since the API remains accessible).

Programmatic Validation

You can verify token access programmatically using the Config class:

from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")

if token:
    print(f"GitHub token configured: {token[:8]}...")
else:
    print("No GitHub token found")

This reads the token from the configuration file or environment variable, following the fallback logic defined in agent_reach/config.py.

Security and File Permissions

Agent-Reach prioritizes token security through filesystem permissions. The Config.save method explicitly sets file permissions to 0600 (owner read/write only) when writing ~/.agent-reach/config.yaml. This prevents other users on the system from reading your GitHub credentials.

For additional security, use a fine-grained Personal Access Token with minimal scopes. Agent-Reach only requires read access to repositories; the default "no scope" token works for basic private repo access, though you may need repo scope for specific operations.

Summary

• Store tokens using agent-reach configure github-token <TOKEN> which writes to ~/.agent-reach/config.yaml via Config.set.
• File location is ~/.agent-reach/config.yaml with the key github_token, secured with 0600 permissions.
• Fallback support allows using the GITHUB_TOKEN environment variable if the config file lacks the key.
• Verification occurs through agent-reach doctor or the GitHubChannel.check method in agent_reach/channels/github.py.

Frequently Asked Questions

Where does Agent-Reach store the GitHub token?

Agent-Reach stores the token in ~/.agent-reach/config.yaml under the github_token key. The Config.save method in agent_reach/config.py creates this file with strict 0600 permissions, ensuring only your user account can read the sensitive 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) checks for the GITHUB_TOKEN environment variable (uppercase) as a fallback. If github_token is not set in the YAML file, Agent-Reach automatically uses the environment variable value.

What GitHub token scopes does Agent-Reach require?

Agent-Reach works with a default "no scope" token for basic private repository access. However, if you encounter permission errors, generate a token with the repo scope at https://github.com/settings/tokens to ensure full read access to private repositories.

How do I verify my token is working correctly?

Run agent-reach doctor to execute the health check implemented in agent_reach/channels/github.py. This validates the token against the GitHub API. Alternatively, check ~/.agent-reach/config.yaml directly to confirm the github_token key exists and contains your token value.

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