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

> Easily configure GitHub tokens for private repository access in Agent Reach. Securely save your PAT to authenticate the embedded gh CLI and access your private repos.

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

---

**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)](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)](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:

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

```

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

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

```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)](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:

```python

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

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

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- Use `agent-reach configure github-token <PAT>` to write the token via the logic in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- The `GitHubChannel.check` method in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.