# How to Configure GitHub Personal Access Tokens for Agent Reach to Access Private Repositories

> Securely grant Agent Reach access to private GitHub repositories. Learn how to configure your GitHub Personal Access Token in Agent Reach with our quick guide.

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

---

**Run `agent-reach configure github-token <YOUR_TOKEN>` to store your GitHub Personal Access Token in `~/.agent-reach/config.yaml`, enabling Agent Reach to authenticate against private repositories.**

Agent Reach stores authentication credentials in a local YAML configuration file and retrieves them via the `Config` class when interacting with the GitHub API. To access private repositories, you must provide a Personal Access Token (PAT) that the tool reads from disk or from the `GITHUB_TOKEN` environment variable.

## Creating a GitHub Personal Access Token

Agent Reach does not require special OAuth scopes for basic repository access. Generate a token with default permissions:

1. Navigate to [https://github.com/settings/tokens](https://github.com/settings/tokens).
2. Click **Generate new token (classic)**.
3. Leave all scopes unchecked—the default "no scope" token supports reading private repositories.
4. Copy the token immediately; GitHub displays it only once.

## Configuring the Token via CLI

The recommended configuration method uses the built-in `configure` subcommand. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101–1103), the CLI parses the `github-token` argument and invokes `config.set("github_token", value)`:

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

```

The command writes the value to `~/.agent-reach/config.yaml` through the `Config.set` method defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 27–33).

## Understanding the Configuration File

Agent Reach persists settings in `~/.agent-reach/config.yaml`. The `Config.save` method (lines 49–66 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) creates this file with **0600** permissions (read/write for owner only) to protect sensitive credentials.

After configuration, the file contains:

```yaml
github_token: ghp_xxxxxxxxxxxxxxxxxxxx

```

## Environment Variable Fallback

If the configuration file does not contain a token, `Config.get` (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. Set it in your shell profile:

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

```

This takes precedence only if the YAML file lacks the `github_token` key.

## Verifying Authentication

Run the diagnostic command to confirm the GitHub channel can authenticate:

```bash
agent-reach doctor

```

The `GitHubChannel.check` method (lines 19–43 in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py)) validates connectivity. A valid token returns `ok`; missing CLI tools may return `warn` but the token remains usable for direct API calls.

## Programmatic Access

Read the token in Python using the internal API:

```python
from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")
print(f"Authenticated with: {token[:8]}...")

```

This retrieves the value from memory, falling back to the environment variable if unset.

## Summary

- **Storage location:** `~/.agent-reach/config.yaml` with restricted **0600** permissions.
- **CLI command:** `agent-reach configure github-token <TOKEN>` writes to [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) via `Config.set`.
- **Config key:** `github_token` is read by `Config.get` with fallback to `GITHUB_TOKEN` environment variable.
- **Verification:** `agent-reach doctor` uses `GitHubChannel.check` in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) to validate authentication.
- **Scope requirements:** No special GitHub scopes required for private repository access.

## Frequently Asked Questions

### Do I need specific GitHub scopes for Agent Reach?

No. According to the source implementation in `Panniantong/Agent-Reach`, the default "no scope" Personal Access Token is sufficient for Agent Reach to read and search private repositories. The token only needs basic authentication permissions.

### Where is the GitHub token stored on disk?

Agent Reach writes the token to `~/.agent-reach/config.yaml` under the key `github_token`. The `Config.save` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 49–66) sets file permissions to `0600`, ensuring only your user account can read the credential.

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

Yes. The `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69–77) checks for the `GITHUB_TOKEN` environment variable (uppercase) if the configuration file entry is missing. Set `export GITHUB_TOKEN=ghp_...` in your shell to use this fallback mechanism.

### How do I verify the token is working correctly?

Run `agent-reach doctor`. The health check 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 authenticates against the GitHub API using your stored token. Success indicates the token is valid and Agent Reach can access private repositories.