How to Set Up GitHub Token Authentication for Private Repositories with Agent Reach

Agent Reach authenticates to private GitHub repositories using a Personal Access Token stored in ~/.agent-reach/config.yaml under the github_token key, which you can configure via the agent-reach configure github-token CLI command.

The open-source Panniantong/Agent-Reach project provides a unified interface for AI agents to interact with various channels, including private GitHub repositories. Setting up GitHub token authentication is essential for enabling read operations on private repos, and the configuration is handled through a secure local YAML file and a simple CLI interface.

Where Agent Reach Stores Authentication Credentials

Agent Reach persists user-specific settings in a YAML configuration file located at ~/.agent-reach/config.yaml. The Config class in agent_reach/config.py manages this file, ensuring sensitive tokens are written with restrictive permissions.

The specific key for GitHub authentication is github_token. When you run the configuration command, the CLI invokes Config.set("github_token", value) (lines 27-33 in agent_reach/config.py), which writes the token to disk with 0600 permissions (read/write for owner only) via the Config.save method.

Configure Your GitHub Personal Access Token

Generate a PAT on GitHub

Before configuring Agent Reach, create a Personal Access Token on GitHub:

1. Navigate to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic) or visit https://github.com/settings/tokens.
2. Click Generate new token and select the appropriate token type.
3. Leave all scopes unchecked—Agent Reach does not require any special permissions to read private repositories; a token with no scopes works for basic repository access.
4. Copy the generated token immediately (GitHub displays it only once).

Store the Token Using the CLI

The recommended method for storing your token is through the Agent Reach CLI. In agent_reach/cli.py (lines 1101-1103), the parser handles the configure sub-command with the github-token argument and persists the value:

agent-reach configure github-token <YOUR_TOKEN>

Upon successful execution, the CLI outputs: ✅ GitHub token configured!

Verify the Configuration File

Confirm the token was written correctly by inspecting the configuration file:

cat ~/.agent-reach/config.yaml

You should see the entry:

github_token: ghp_xxxxxxxxxxxxxxxxxxxx

The file permissions are automatically set to 0600 to prevent unauthorized access.

How Agent Reach Uses the Token

When the GitHubChannel needs to authenticate API requests, it retrieves the token through the Config.get("github_token") method (lines 69-77 in agent_reach/config.py). This method implements a fallback hierarchy:

1. First checks the in-memory configuration dictionary
2. Then checks the environment variable GITHUB_TOKEN (uppercase)
3. Finally reads from the ~/.agent-reach/config.yaml file

The GitHubChannel.check method in agent_reach/channels/github.py (lines 19-43) validates the configuration during the health check process, verifying that the token is present and functional.

Code Examples

Configure via CLI

# Set the token interactively

agent-reach configure github-token ghp_abcdefghijklmnopqrstuvwxyz1234

# Verify the configuration

agent-reach doctor

Access Token Programmatically

from agent_reach.config import Config

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

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

Manual Configuration File Editing

For advanced users who prefer direct file manipulation:

# ~/.agent-reach/config.yaml

github_token: ghp_your_personal_access_token_here

Ensure the file permissions remain secure:

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

Summary

• Agent Reach stores GitHub tokens in ~/.agent-reach/config.yaml under the github_token key, managed by the Config class in agent_reach/config.py.
• Use the command agent-reach configure github-token <TOKEN> to securely store credentials via the CLI.
• The configuration file is created with 0600 permissions to protect sensitive data.
• The GitHubChannel retrieves tokens via Config.get("github_token"), which supports environment variable fallbacks.
• Verify your setup with agent-reach doctor to confirm the GitHub channel reports healthy authentication status.

Frequently Asked Questions

What permissions does the GitHub token need for Agent Reach?

Agent Reach requires no special scopes to access private repositories. When generating your Personal Access Token on GitHub, you can leave all permission scopes unchecked. The token only needs basic repository read access, which is granted by default to tokens with no scopes selected.

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

Yes. According to the Config.get implementation in agent_reach/config.py (lines 69-77), Agent Reach checks for the GITHUB_TOKEN environment variable (uppercase) before falling back to the configuration file. This allows you to export tokens in CI/CD environments without writing to disk: export GITHUB_TOKEN=ghp_xxxxxxxx.

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

Run the diagnostic command agent-reach doctor. This executes the GitHubChannel.check method in agent_reach/channels/github.py, which validates that your token can authenticate with GitHub's API. If the token is valid, the output shows ok for the GitHub channel; if gh CLI is missing but the token is valid, it may show warn while remaining functional.

Is the GitHub token stored securely by Agent Reach?

Yes. The Config.save method explicitly sets file permissions to 0600 (read and write for owner only) when writing ~/.agent-reach/config.yaml. This prevents other users on the system from reading your authentication credentials, following Unix security best practices for sensitive configuration files.

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