How to Configure a GitHub Token for the GitHub Channel in Agent Reach

Store your GitHub token securely in ~/.agent-reach/config.yaml using the built-in CLI command to enable full read-write access to private repositories and issue management.

Agent Reach is an open-source automation framework that integrates with GitHub through a dedicated channel. To configure a GitHub token for the GitHub channel, you use the Config class to persist credentials locally and the GitHubChannel class to authenticate API requests. This setup allows the tool to escalate from read-only public repository access to full private repository management, issue creation, and pull request workflows.

Understanding the GitHub Channel Architecture

The GitHub channel implementation resides in agent_reach/channels/github.py. The GitHubChannel class provides two operational modes determined by its check() method.

When the channel initializes, it probes the local gh CLI (the official GitHub command-line tool) to verify installation and authentication status. If the CLI reports an authenticated session, the channel enables full functionality. Without authentication, the channel falls back to read-only mode and surfaces a warning to the user.

Configuration Storage and Security Model

Token persistence is handled by the Config class in agent_reach/config.py. When you configure a GitHub token for the GitHub channel, the set("github_token", value) method writes the key to ~/.agent-reach/config.yaml with 600 permissions (owner-only read/write).

The security model ensures the token never leaves your local machine. The to_dict() method masks the token value when displaying configuration, and the runtime system excludes the token from all logs and public output.

Step-by-Step Configuration Methods

Using the CLI Command

The simplest way to configure a GitHub token for the GitHub channel is through the registered sub-command in agent_reach/cli.py (lines 1122-1124). This interface validates input and handles file permissions automatically.

agent-reach configure github-token ghp_YourGeneratedTokenHere

Upon execution, the CLI invokes config.set("github_token", value) and prints a confirmation message. The token is immediately available for subsequent GitHub channel operations.

Manual Configuration

You can also edit the configuration file directly. This is useful when migrating settings or using configuration management tools.

$EDITOR ~/.agent-reach/config.yaml

Add or update the following entry:

github_token: ghp_YourGeneratedTokenHere

Ensure the file permissions remain restricted to your user:

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

Verifying the Configuration

To confirm the token is stored correctly without exposing the full value, use the diagnostic command:

agent-reach doctor | grep "GitHub"

Expected output:

GitHub token: ghp_YourGe… (masked)

Runtime Token Usage

When processing requests, the GitHub channel retrieves the token via config.get("github_token"). If present, the channel injects the Authorization: token <TOKEN> header into underlying gh CLI commands or direct API calls.

This authentication enables private repository access and write operations. The following Python snippet demonstrates how the channel internally passes the token to subprocess calls:

import subprocess
import json
import os

token = os.getenv("GITHUB_TOKEN") or config.get("github_token")
result = subprocess.run(
    ["gh", "repo", "view", "your-private-org/private-repo", "--json", "name,description"],
    capture_output=True,
    text=True,
    env={**os.environ, "GITHUB_TOKEN": token},
)
print(json.loads(result.stdout))

Because the token is cached in the configuration, the gh CLI authenticates automatically without interactive prompts.

Summary

• Location: Tokens are stored in ~/.agent-reach/config.yaml via the Config class in agent_reach/config.py.
• Security: File permissions are set to 600, and tokens are masked in configuration displays and logs.
• CLI Command: Use agent-reach configure github-token <TOKEN> to persist credentials (implemented in agent_reach/cli.py).
• Channel Logic: The GitHubChannel class in agent_reach/channels/github.py uses the check() method to verify gh CLI authentication and enable full access.
• Runtime: The token is retrieved via config.get("github_token") and injected as an Authorization header for API requests.

Frequently Asked Questions

Where is the GitHub token stored when I configure it?

The token is stored in the local YAML file at ~/.agent-reach/config.yaml under the key github_token. The Config class in agent_reach/config.py handles the write operation with strict 600 permissions, ensuring only the file owner can read or modify the value.

Can I use the GitHub channel without a token?

Yes, but with limitations. According to the GitHubChannel.check() method in agent_reach/channels/github.py, the channel will operate in read-only mode for public repositories if the gh CLI is not authenticated. To access private repositories or create issues and pull requests, you must configure a GitHub token for the GitHub channel.

How do I verify that my token is working correctly?

Run agent-reach doctor and grep for "GitHub" in the output. The diagnostic tool calls the configuration's to_dict() method, which displays a masked version of the token (e.g., ghp_YourGe…). If the token is missing or the gh CLI is not authenticated, the check will report warnings regarding limited functionality.

Is it safe to store my GitHub token in Agent Reach?

Yes. The implementation in agent_reach/config.py ensures the token never leaves your local machine. The file is created with 600 permissions, the token is excluded from logs, and the to_dict() method masks the value when displaying configuration. The token is only used to set the GITHUB_TOKEN environment variable for local gh CLI subprocess calls.

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