# How to Configure a GitHub Personal Access Token for Private Repositories in Agent Reach

> Configure your GitHub personal access token for private repositories in Agent Reach. Learn how to set your token via CLI for authenticated access to Panniantong/Agent-Reach.

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

---

**Agent Reach stores GitHub Personal Access Tokens in `~/.agent-reach/config.yaml` under the `github_token` key, which you can set via the CLI using `agent-reach configure github-token <TOKEN>` to enable authenticated access to private repositories.**

To work with private GitHub repositories, Agent Reach requires a Personal Access Token (PAT) for authentication. According to the Panniantong/Agent-Reach source code, the tool handles token storage, retrieval, and validation through a centralized configuration system that supports both file-based and environment variable configurations.

## Where Agent Reach Stores the GitHub Token

Agent Reach maintains user-specific settings in a YAML file located at `~/.agent-reach/config.yaml`. The **`github_token`** key holds the value used to authenticate with the GitHub API.

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config.set` method (lines 27-33) handles writing values to this configuration file. When you save a token, the `Config.save` method (lines 49-66) persists the data to disk with **permissions `0600`** (read/write for the owner only), ensuring the token remains private from other system users.

## Configuring the Token via CLI

### 1. Generate a Personal Access Token on GitHub

Navigate to [https://github.com/settings/tokens](https://github.com/settings/tokens) and generate a new token. Agent Reach does **not** require any special scopes—the default "no scope" token provides sufficient permissions for reading private repositories. Copy the generated token immediately, as GitHub displays it only once.

### 2. Store the Token Using the Configure Command

Run the following command to securely save your token:

```bash
agent-reach configure github-token <YOUR_TOKEN>

```

The CLI code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103) parses the `github-token` argument and invokes `config.set("github_token", value)` to persist the entry. Upon success, the CLI prints "✅ GitHub token configured!" confirming the operation.

### 3. Verify the Configuration File (Optional)

Confirm the token was written correctly by inspecting the configuration file:

```bash
cat ~/.agent-reach/config.yaml

```

You should see the entry:

```yaml
github_token: ghp_xxxxxxxxxxxxxxxxxxxx

```

### 4. Validate the Connection

Run the health check to verify the token works:

```bash
agent-reach doctor

```

This invokes `GitHubChannel.check` in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-43), which validates the token against the GitHub API. Valid configurations report `ok`; missing `gh` CLI installations may report `warn` but the token remains functional for direct API calls.

## How the Token is Loaded at Runtime

Agent Reach retrieves the token using the `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-77). The system checks values in the following priority order:

1. **In-memory configuration** dictionary
2. **Environment variable** `GITHUB_TOKEN` (uppercase)
3. **Configuration file** (`~/.agent-reach/config.yaml`)

This hierarchy allows temporary overrides via environment variables without modifying the config file. The `GitHubChannel` class uses this retrieved token to authenticate API requests or invoke the `gh` CLI when available.

## Manual Configuration (Advanced)

You can directly edit the configuration file instead of using the CLI:

```yaml

# ~/.agent-reach/config.yaml

github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

```

Ensure the file maintains `0600` permissions after editing to prevent unauthorized access.

## Programmatic Access

For custom scripts or extensions, access the token programmatically through the `Config` class:

```python
from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")  # Returns string or None

# Masked output for safety

if token:
    print("GitHub token:", token[:8] + "...")

```

## Summary

- Agent Reach stores tokens in **`~/.agent-reach/config.yaml`** under the **`github_token`** key
- Use **`agent-reach configure github-token <TOKEN>`** to set values via CLI (implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), lines 1101-1103)
- Configuration files use **`0600` permissions** to restrict access to the owner only
- The **`Config.get`** method checks the in-memory cache, then **`GITHUB_TOKEN`** environment variable, then the config file (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py))
- No special GitHub scopes are required for private repository access
- Verify setup using **`agent-reach doctor`**, which triggers `GitHubChannel.check`

## Frequently Asked Questions

### Do I need specific scopes for the GitHub Personal Access Token?

No. According to the Agent Reach implementation, the default "no scope" token works for reading private repositories. You do not need to assign `repo` or other scopes unless you plan to perform write operations beyond the tool's standard read/search functionality.

### Can I use an environment variable instead of the config file?

Yes. The `Config.get` method (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) falls back to the `GITHUB_TOKEN` environment variable if the key is not set in the configuration file or in-memory cache. Set `export GITHUB_TOKEN=ghp_...` in your shell to override the config file temporarily.

### Where is the Agent Reach configuration file stored?

The configuration file is located at **`~/.agent-reach/config.yaml`** on Unix-like systems. The `Config.save` method creates this file with **`0600` permissions** (readable only by the owner) to protect sensitive tokens stored within.

### How do I verify my GitHub token is configured correctly?

Run **`agent-reach doctor`** to execute the health check logic in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-43). This validates that the token can authenticate with the GitHub API. If the `gh` CLI is installed, it also verifies CLI integration. A valid token produces an `ok` status in the GitHub section of the output.