How to Configure GitHub Tokens for Private Repository Access in Agent Reach

Run agent-reach configure github-token <PAT> to save your Personal Access Token to ~/.agent-reach/config.yaml, which lets the embedded gh CLI authenticate and access private repositories.

Agent Reach relies on the official GitHub CLI (gh) to interact with source code, and configuring GitHub tokens for private repository access is handled through a dedicated configuration key. The repository Panniantong/Agent-Reach stores the token locally and validates authentication before executing any repository-scoped commands. Understanding the exact file paths and CLI commands ensures you can grant the agent secure, rate-limited access to your private code without unnecessary permissions.

Where Agent Reach Stores Your GitHub Token

The token is persisted in ~/.agent-reach/config.yaml under the key github_token. This mapping is defined in the configuration schema inside [agent_reach/config.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py#L26) at line 26.

When you run the configure command, the CLI writes the value through the configuration object. The relevant branching logic lives in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py#L1115-L1117) around lines 1115–1117. A simplified view of that handler looks like this:

# 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!")

Using the CLI to Configure Your GitHub Token

The fastest way to set up private repository access is through the built-in configure sub-command.

1. Generate a Personal Access Token by visiting https://github.com/settings/tokens. The project documentation notes that no scopes are required for read-only access.

2. Store the token with Agent Reach:

agent-reach configure github-token ghp_YourPersonalAccessTokenHere

Alternative: Edit config.yaml Directly

If you prefer manual setup, add the following line to ~/.agent-reach/config.yaml:

github_token: ghp_YourPersonalAccessTokenHere

How the Token Unlocks Private Repositories

After configuration, the GitHubChannel class verifies that the gh binary is installed and authenticated. In [agent_reach/channels/github.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py#L19-L30) (lines 19–30), the check method executes gh auth status via subprocess and interprets the result:

# Inside 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 r.returncode == 0, the channel returns full capability, including read, search, fork, issue, and PR access. Without authentication, gh can only reach public repositories and is heavily rate-limited.

Rate Limits and Why Authentication Matters

According to the README installation section, unauthenticated requests to the GitHub API are limited to 60 requests per hour. Once you configure a PAT, that limit increases to 5,000 requests per hour, and private repositories become reachable. This distinction is what makes configuring GitHub tokens for private repository access a required step for any non-public workflow in Agent Reach.

Verify Your Setup

Run the built-in health check to confirm everything is working:

agent-reach doctor

A working configuration prints GitHub OK alongside the gh CLI authenticated status. You can then test private access with a command like:

gh repo view yourname/private-repo

Summary

• Agent Reach stores the GitHub PAT in ~/.agent-reach/config.yaml under the key github_token, defined in agent_reach/config.py.
• Use agent-reach configure github-token <PAT> to write the token via the logic in agent_reach/cli.py.
• The GitHubChannel.check method in agent_reach/channels/github.py validates authentication by calling gh auth status.
• Authenticated users get 5,000 requests/hour and full read/search/fork/issue/PR capabilities on private repos.
• Verify the setup with agent-reach doctor before running private repository commands.

Frequently Asked Questions

Do I need to select any scopes when creating the GitHub PAT?

No. The Agent Reach README explicitly states that no scopes are required for read-only access. Simply generate a classic or fine-grained Personal Access Token without additional permissions and configure it via the CLI.

Where exactly does Agent Reach save my GitHub token?

The token is saved in ~/.agent-reach/config.yaml under the key github_token. This path is printed during installation and is managed by the Config class defined in agent_reach/config.py at line 26.

How can I verify that my GitHub token is active in Agent Reach?

Run agent-reach doctor. The health check invokes the GitHubChannel.check logic in agent_reach/channels/github.py, which executes gh auth status. If the return code is zero, the output shows GitHub OK and confirms full capability for private repositories.

Can I use Agent Reach with private repositories without a token?

No. The gh CLI requires a Personal Access Token to access private repositories. Without one, Agent Reach is restricted to public repositories and a rate limit of 60 requests per hour, as documented in the README installation section.

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