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

> Learn to configure GitHub personal access tokens for Agent Reach private repository access. Securely store your token using the CLI command for seamless integration.

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

---

**To configure GitHub personal access tokens for private repository access in Agent Reach, use the CLI command `agent-reach configure github-token <TOKEN>` to store the token in `~/.agent-reach/config.yaml`, which the `GitHubChannel` class reads via `Config.get("github_token")`.**

The open-source Agent Reach project (Panniantong/Agent-Reach) authenticates to private GitHub repositories using personal access tokens managed through a central configuration system. This guide explains how to configure GitHub personal access tokens for private repository access in Agent Reach using the built-in `Config` class and CLI tools.

## Understanding the Configuration Architecture

Agent Reach stores user-specific settings in a YAML file located at `~/.agent-reach/config.yaml`. The central configuration logic resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), where the `Config` class handles persistence and retrieval. When you configure a GitHub token, the system writes to the `github_token` key using the `Config.set` method (lines 27-33), which atomically saves the value to disk with secure permissions.

## Step-by-Step Configuration Guide

### Generate a GitHub Personal Access Token

Visit https://github.com/settings/tokens to create a new token. You do not need any special scopes for Agent Reach; the default "no scope" token works for reading private repositories. Copy the generated token immediately, as GitHub displays it only once.

### Store the Token via CLI

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

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

```

The CLI confirms with "✅ GitHub token configured!" and persists the value to `~/.agent-reach/config.yaml`.

### Verify File Creation

The `Config.save` method (lines 49-66) creates the configuration directory and file with `0600` permissions (read/write for owner only). Verify the token exists:

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

```

Expected output:

```yaml
github_token: ghp_your_token_here

```

## How Agent Reach Retrieves the Token

The `Config.get` method (lines 69-77) implements a fallback chain: it first checks the in-memory configuration dictionary, then falls back to the `GITHUB_TOKEN` environment variable (uppercase). This allows flexibility between persistent configuration and temporary environment-based authentication.

The `GitHubChannel` class in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) uses this token to authenticate API requests. The `GitHubChannel.check` method (lines 19-43) performs health checks to verify the token works with either the authenticated `gh` CLI or direct API calls.

## Alternative Configuration Methods

### Environment Variable Override

Set the token temporarily without writing to disk:

```bash
export GITHUB_TOKEN=ghp_your_token_here

```

This takes precedence over the configuration file when using `Config.get("github_token")`.

### Manual Configuration File Editing

Advanced users can edit `~/.agent-reach/config.yaml` directly:

```yaml
github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

```

## Verification and Troubleshooting

Run the diagnostic command to verify your setup:

```bash
agent-reach doctor

```

This executes `GitHubChannel.check` and reports whether the token is valid. If the `gh` CLI is missing, the check may warn but still report success if the token is valid for API calls.

## Summary

- Agent Reach stores GitHub tokens in `~/.agent-reach/config.yaml` under the `github_token` key.
- Use `agent-reach configure github-token <TOKEN>` to write the configuration via `Config.set` in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- The system creates the config file with `0600` permissions for security.
- `Config.get` checks the in-memory dict first, then falls back to the `GITHUB_TOKEN` environment variable.
- Verify authentication works using `agent-reach doctor`, which invokes `GitHubChannel.check` in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py).

## Frequently Asked Questions

### Where does Agent Reach store my GitHub token?

Agent Reach writes the token to `~/.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) sets file permissions to `0600`, ensuring only your user account can read or write the file.

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

Yes. The `Config.get` method checks for `GITHUB_TOKEN` (uppercase) as a fallback after checking the in-memory configuration. This is useful for CI/CD pipelines or temporary sessions where you don't want to persist credentials to disk.

### What permissions does my GitHub token need?

You do not need any special scopes for Agent Reach. The default "no scope" personal access token provides sufficient permissions to read private repositories. Generate yours at https://github.com/settings/tokens.

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

Run `agent-reach doctor` to execute the health check. 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) validates the token by attempting authenticated API calls, reporting `ok` if successful.