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

Run agent-reach configure github-token <YOUR_PAT> to store your Personal Access Token in ~/.agent-reach/config.yaml, enabling the gh CLI to authenticate against private repositories and increasing your API rate limit from 60 to 5,000 requests per hour.

Agent-Reach leverages the official GitHub CLI (gh) to read, search, and interact with repositories, which requires a GitHub personal access token for private repository access. According to the Panniantong/Agent-Reach source code, the token is stored in a local YAML configuration and validated through the gh auth status command before executing operations.

Why You Need a Token for Private Repositories

Without authentication, the gh CLI is restricted to public repositories and subject to a 60 request/hour rate limit. By configuring a Personal Access Token (PAT), you unlock private repository access and benefit from a 5,000 request/hour rate limit, enabling full read, search, fork, issue, and PR operations.

Configuring Your GitHub Personal Access Token

1. Generate a Personal Access Token

Navigate to https://github.com/settings/tokens and generate a new classic token. For read-only repository access, no specific scopes are required—the Agent-Reach README explicitly notes that "无需任何权限" (no permissions are needed).

2. Store the Token via CLI

Execute the configure command to write the token to your local configuration:

agent-reach configure github-token ghp_YourPersonalAccessTokenHere

Internally, this invokes the configuration handler in agent_reach/cli.py (lines 1115-1117), which executes the following logic:

# Inside agent_reach/cli.py

elif args.key == "github-token":
    config.set("github_token", value)        # store in ~/.agent-reach/config.yaml

    print("✅ GitHub token configured!")

3. Verify Authentication

Run the health check to confirm the gh CLI recognizes your credentials:

agent-reach doctor

You should see "GitHub OK" indicating successful authentication.

How Agent-Reach Uses Your Token

Configuration Schema

The token is defined in the configuration schema at agent_reach/config.py (line 26) under the key github_token. When persisted, it is written to ~/.agent-reach/config.yaml.

Authentication Validation

The GitHubChannel class validates authentication by executing gh auth status via subprocess, as implemented in agent_reach/channels/github.py (lines 19-30):

# From agent_reach/channels/github.py

def check(self, config=None):
    gh = shutil.which("gh")
    if not gh:
        return "warn", "gh CLI 未安装。安装：https://cli.github.com"
    try:
        r = subprocess.run([gh, "auth", "status"], capture_output=True,
                           encoding="utf-8", errors="replace", timeout=5)
        if r.returncode == 0:
            return "ok", "完整可用（读取、搜索、Fork、Issue、PR 等）"
        return "warn", "gh CLI 已安装但未认证。运行 gh auth login 可解锁完整功能"
    except Exception:
        return "warn", "gh CLI 状态检查失败，运行 gh auth status 查看详情"

If the token is valid, the channel reports full capability for private repository operations.

Rate Limiting Benefits

As documented in the README installation section, authenticated requests enjoy a 5,000 request/hour limit compared to 60 requests/hour for unauthenticated access, preventing throttling during high-volume operations.

Manual Configuration Alternative

If you prefer editing the configuration file directly, add the following to ~/.agent-reach/config.yaml:

github_token: ghp_YourPersonalAccessTokenHere

Summary

• Agent-Reach requires a GitHub Personal Access Token to access private repositories via the gh CLI
• Store tokens using agent-reach configure github-token <TOKEN> or by editing ~/.agent-reach/config.yaml directly
• The configuration schema is defined in agent_reach/config.py (line 26) and the CLI handler resides in agent_reach/cli.py (lines 1115-1117)
• Authentication is validated by GitHubChannel.check() in agent_reach/channels/github.py (lines 19-30) using gh auth status
• Authenticated users receive 5,000 API requests per hour versus 60 for unauthenticated access

Frequently Asked Questions

Do I need specific scopes for the GitHub personal access token?

No. For read-only access to private repositories, you do not need to select any scopes when creating the token. The Agent-Reach documentation explicitly states that no permissions are required ("无需任何权限") for basic repository reading and searching operations.

Where is the GitHub token stored locally?

The token is stored in ~/.agent-reach/config.yaml under the github_token key. This location is defined in the configuration schema at agent_reach/config.py (line 26) and is written by the CLI command handler in agent_reach/cli.py (lines 1115-1117).

How can I verify that my token is configured correctly?

Run agent-reach doctor to execute a health check. The tool runs gh auth status via subprocess as implemented in agent_reach/channels/github.py (lines 19-30). If authentication succeeds, you will see "GitHub OK" and confirmation that the CLI has full capability for private repository access.

What happens if I don't configure a personal access token?

Without a token, Agent-Reach can only access public repositories and is subject to GitHub's unauthenticated rate limit of 60 requests per hour. Private repositories will be inaccessible, and you may encounter rate limiting errors during high-volume operations.

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