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

> Securely configure your GitHub personal access token for Agent Reach private repository access. Learn the simple command to add your token for seamless integration.

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

---

**Configure your GitHub personal access token in Agent Reach by running `agent-reach configure github-token <TOKEN>`, which securely stores the credential in `~/.agent-reach/config.yaml` with `0600` permissions for private repository access.**

Agent Reach requires authentication to read private repositories through the GitHub API. This guide explains how to securely store a personal access token using the CLI configuration commands and how the credential is managed internally by the `Config` class in the Panniantong/Agent-Reach repository.

## Where Agent Reach Stores Authentication Credentials

Agent Reach maintains user-specific settings in a YAML configuration file located at `~/.agent-reach/config.yaml`. The `github_token` key holds the personal access token used for authenticating with private GitHub repositories.

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles persistence through the `set` method (lines 27-33), which writes values to this file. When saving credentials, the `Config.save` method (lines 49-66) sets file permissions to `0600`, ensuring only the file owner can read or write the token.

## Step-by-Step Configuration Guide

### Generate a Personal Access Token on GitHub

Create a token with default permissions that grants read access to private repositories:

1. Navigate to https://github.com/settings/tokens
2. Click **"Generate new token (classic)"**
3. Provide a descriptive name (e.g., "Agent Reach Access")
4. Leave all scopes unchecked—Agent Reach requires no special scopes for repository reading
5. Click **"Generate token"** and copy the value immediately

### Store the Token Using the CLI

Use the `configure` sub-command with the `github-token` argument to persist the token:

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

```

The CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103) parses this argument and calls `config.set("github_token", value)`, writing the token to your configuration file. The command outputs "✅ GitHub token configured!" upon successful storage.

### Verify the Configuration

Confirm the token was saved correctly:

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

```

You should see the `github_token` entry:

```yaml
github_token: ghp_your_token_here

```

Run the health check to validate authentication:

```bash
agent-reach doctor

```

The `GitHubChannel.check` method in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-43) verifies the token works with the GitHub API, reporting `ok` if authentication succeeds.

## How the Token Is Used Internally

Agent Reach retrieves the token through the `Config.get` method (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)), which implements a fallback hierarchy:

1. **In-memory cache**: Checks the loaded configuration dictionary first
2. **Environment variable**: Falls back to `GITHUB_TOKEN` (uppercase) if not found in config
3. **Return None**: If neither source provides the token

The `GitHubChannel` class uses this token to authenticate API requests, either through the authenticated `gh` CLI when available or via direct API calls using the stored credential.

## Configuration Code Examples

**Set token via CLI (recommended):**

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

```

**Read token programmatically:**

```python
from agent_reach.config import Config

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

```

**Manual configuration (advanced):**

Edit `~/.agent-reach/config.yaml` directly:

```yaml
github_token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

Ensure the file maintains `0600` permissions after manual editing:

```bash
chmod 600 ~/.agent-reach/config.yaml

```

## Summary

- Agent Reach stores GitHub tokens in `~/.agent-reach/config.yaml` under the `github_token` key
- Use `agent-reach configure github-token <TOKEN>` to set credentials securely via the CLI
- The configuration file uses `0600` permissions to protect the token from unauthorized access
- The `Config.get` method checks the config file first, then falls back to the `GITHUB_TOKEN` environment variable
- Verify authentication works by running `agent-reach doctor` to execute the `GitHubChannel.check` health verification

## Frequently Asked Questions

### Where does Agent Reach store the GitHub personal access token?

Agent Reach stores the token in the YAML file at `~/.agent-reach/config.yaml` under the `github_token` key. The `Config.save` method 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 ensure the credential remains private and inaccessible to other system users.

### Can I use an environment variable instead of the configuration 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) implements a fallback mechanism that checks for the `GITHUB_TOKEN` environment variable (uppercase) if the `github_token` key is not present in the configuration file. This allows temporary or CI/CD-based authentication without persisting credentials to disk.

### What GitHub scopes or permissions does the token require?

Agent Reach requires no special scopes for accessing private repositories. When generating the token at https://github.com/settings/tokens, you can leave all scope checkboxes unchecked. The default "no scope" token provides sufficient permissions for the read and search operations performed by the `GitHubChannel` class in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py).

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

Run `agent-reach doctor` to execute the health check system. 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 the token by attempting to authenticate with the GitHub API. A successful check returns `ok`, while configuration issues result in `warn` or error states that indicate whether the token is invalid, missing, or the `gh` CLI is unavailable.