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

> Secure Agent Reach access to private GitHub repositories by configuring your GitHub token. Learn how to set it via command or environment variable for seamless integration.

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

---

**Agent Reach stores GitHub authentication credentials in `~/.agent-reach/config.yaml` under the `github_token` key, which you can set via the `agent-reach configure github-token <TOKEN>` command or the `GITHUB_TOKEN` environment variable.**

Agent Reach requires a GitHub personal access token to clone and analyze code from private repositories. According to the Panniantong/Agent-Reach source code, the tool centralizes all user credentials in a YAML configuration file and exposes a simple CLI interface for secure token management.

## Where Credentials Are Stored

The configuration system is implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). All user-specific settings persist to `~/.agent-reach/config.yaml` with restrictive file permissions (`0600`). The specific key for GitHub authentication is **`github_token`**.

When the CLI receives the `configure` subcommand, it calls `Config.set("github_token", value)` (lines 27-33 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)), which writes the value to disk through the `Config.save` method (lines 49-66). This ensures your token is readable only by your user account.

## Step-by-Step Configuration

### 1. Generate a GitHub Personal Access Token

Navigate to https://github.com/settings/tokens and create a new token. Agent Reach only requires read access to private repositories, so you can create a token with **no scopes** selected. Copy the generated token immediately—it displays only once.

### 2. Configure Agent Reach via CLI

The recommended method uses the configure subcommand implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103):

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

```

The CLI maps the argument `github-token` to the internal key `github_token` and persists it via `Config.set`. After execution, the terminal prints "✅ GitHub token configured!" confirming the entry was saved.

### 3. Verify the Configuration

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

```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) validates the token against the GitHub API. If the token is valid and the `gh` CLI is installed, the check reports `ok`.

## Alternative Configuration Methods

### Environment Variable Override

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. If `github_token` is not set in the YAML file, Agent Reach checks for the **`GITHUB_TOKEN`** environment variable (uppercase):

```bash
export GITHUB_TOKEN=ghp_YourTokenHere

```

This is useful for CI/CD pipelines where writing to the filesystem is not permitted.

### Manual File Editing

Advanced users can edit the configuration file directly:

```yaml

# ~/.agent-reach/config.yaml

github_token: ghp_YourGeneratedTokenString

```

The file must remain readable only by the owner (permissions `0600`), which the `Config.save` method enforces automatically.

## Programmatic Token Access

To read the configured token programmatically in Python:

```python
from agent_reach.config import Config

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

# Masked output for logging

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

```

The `Config.get` method first checks the in-memory dictionary, then falls back to the environment variable, ensuring flexibility across deployment environments.

## Summary

- **Storage location**: Agent Reach stores tokens in `~/.agent-reach/config.yaml` under the `github_token` key with `0600` permissions.
- **CLI command**: Use `agent-reach configure github-token <TOKEN>` to persist credentials securely.
- **Environment fallback**: Set `GITHUB_TOKEN` if you prefer environment-based configuration.
- **Verification**: Run `agent-reach doctor` to validate that `GitHubChannel` can authenticate using the stored token.
- **Source references**: Configuration logic resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 27-33, 49-77), CLI parsing in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103), and channel validation in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-43).

## Frequently Asked Questions

### Do I need special scopes for the GitHub token?

No. Agent Reach only requires read access to private repositories, which works with the default "no scope" token. You do not need to enable `repo` or other scopes unless you plan to perform write operations.

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

Yes. According to the `Config.get` implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-77), Agent Reach checks for the uppercase `GITHUB_TOKEN` environment variable if the `github_token` key is not present in the YAML configuration file.

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

Run `agent-reach doctor` in your terminal. This executes the `GitHubChannel.check` method, which validates the token against the GitHub API. A successful check returns `ok` in the GitHub section of the output.

### Is the token stored securely on disk?

Yes. The `Config.save` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 49-66) creates the configuration file with `0600` permissions (read/write for owner only), preventing other users on the system from accessing your GitHub credentials.