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

> Configure your GitHub Personal Access Token for Agent-Reach to access private repositories and boost your API rate limit to 5000/hr. Run agent-reach configure github-token <YOUR_PAT>.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-11

---

**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:

```bash
agent-reach configure github-token ghp_YourPersonalAccessTokenHere

```

Internally, this invokes the configuration handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1115-1117), which executes the following logic:

```python

# 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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-30):

```python

# 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`:

```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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (line 26) and the CLI handler resides in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1115-1117)
- Authentication is validated by `GitHubChannel.check()` in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (line 26) and is written by the CLI command handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.