# How to Configure a GitHub Token for Accessing Private Repositories with Agent Reach

> Learn how to configure a GitHub token for Agent Reach to access private repositories. Discover the three authentication methods for seamless integration.

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

---

**Agent Reach reads a GitHub token from three sources: the config file, the `GH_TOKEN` environment variable, or the `GITHUB_TOKEN` environment variable, enabling seamless authentication for private repositories.**

Agent Reach is an open-source tool that enables programmatic interaction with code repositories. To access private GitHub repositories, you must configure a **GitHub personal access token**. This guide explains exactly how Agent Reach handles token configuration based on the source code in `Panniantong/Agent-Reach`.

## Where Agent Reach Looks for Your Token

The token resolution follows a clear priority order in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py):

1. **`GH_TOKEN`** environment variable
2. **`GITHUB_TOKEN`** environment variable
3. **`github_token`** key in `~/.agent-reach/config.yaml`

The `GitHubChannel.check()` method implements this fallback chain at lines 84-92:

```python

# From agent_reach/channels/github.py

def check(self):
    # First check environment variables

    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
    if not token:
        # Fall back to config file

        token = self.config.get("github_token")
    return token is not None

```

When any of these sources contains a valid token, the `GitHubChannel` authenticates through the `gh` CLI without prompting the user.

## Method 1: Configure via CLI Command

The most direct approach uses the built-in configuration command. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1312-1315), the `configure github-token` subcommand persists your token:

```bash

# Generate a personal access token on GitHub with 'repo' scope first

agent-reach configure github-token ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

```

The CLI writes to `~/.agent-reach/config.yaml` through `Config.set()`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 1110-1112) registers `"github_token"` as a required key for the github_token feature, ensuring validation on access.

Verify the configuration:

```bash
agent-reach doctor

# Expected output: GitHub channel reports "configured"

```

## Method 2: Use Environment Variables

For CI/CD pipelines or temporary configurations, export either variable:

```bash
export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Alternative:

export GH_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

```

With the environment variable set, Agent Reach picks up the token automatically—no config file needed:

```bash
agent-reach doctor   # → GitHub channel reports "configured"

agent-reach read https://github.com/your-org/private-repo/blob/main/README.md

```

This approach skips disk entirely, which is ideal for ephemeral environments.

## Method 3: Programmatic Configuration

For embedded usage or custom tooling, interact with the `Config` class directly:

```python
from agent_reach.config import Config

cfg = Config()
cfg.set("github_token", "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX")

# Verify storage

print(cfg.get("github_token"))  # → ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

```

The `Config` class handles atomic writes with owner-only permissions to prevent symlink attacks, as implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

## Security and Storage Details

| Aspect | Implementation Detail |
|--------|----------------------|
| **File permissions** | Config file written with owner-only access |
| **Write safety** | Atomic file operations prevent partial writes |
| **Environment precedence** | `GH_TOKEN` > `GITHUB_TOKEN` > config file |
| **Doctor limitations** | Verifies token *existence*, not validity—no `gh auth status` call to avoid device-id file creation |

## Complete Workflow Example

```bash

# Step 1: Generate token at https://github.com/settings/tokens (select 'repo' scope)

# Step 2: Configure Agent Reach

agent-reach configure github-token ghp_xxxxxxxxxxxxxxxxxxxx

# Step 3: Verify

agent-reach doctor

# Step 4: Access private repository content

agent-reach read https://github.com/mycompany/internal-api/blob/main/src/main.py

```

## Troubleshooting Private Repository Access

If private repositories remain inaccessible:

- Confirm token has **repo** scope (or appropriate fine-grained permissions)
- Check `agent-reach doctor` reports GitHub channel as configured
- Verify no conflicting `GH_TOKEN`/`GITHUB_TOKEN` values override your config
- Validate token expiration date in GitHub settings

## Summary

- **Three valid sources**: `GH_TOKEN`, `GITHUB_TOKEN`, or config file via `agent-reach configure github-token`
- **CLI convenience**: `agent-reach configure github-token <TOKEN>` persists to `~/.agent-reach/config.yaml`
- **Environment flexibility**: Shell variables work immediately without config file modification
- **Implementation locations**: [`cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cli.py) (command handling), [`config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/config.py) (storage), [`channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/channels/github.py) (runtime resolution)

## Frequently Asked Questions

### What GitHub token permissions does Agent Reach require?

Agent Reach requires the **repo** scope for classic tokens, or equivalent repository read access for fine-grained personal access tokens. The token must grant access to the specific private repositories you intend to read.

### Can I use a GitHub App installation token instead of a personal access token?

The current implementation in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) expects a personal access token format. While the underlying `gh` CLI supports GitHub Apps, Agent Reach's token validation assumes direct personal access token strings.

### Why does `agent-reach doctor` succeed but my private repo access fails?

The doctor command only checks that a token *exists* in configuration or environment—it does not validate the token against GitHub's API. Actual repository access failure typically indicates insufficient token scopes, repository permissions, or token expiration.

### How do I remove a stored GitHub token?

Delete the `github_token` key from `~/.agent-reach/config.yaml` or unset the `GH_TOKEN`/`GITHUB_TOKEN` environment variables. There is currently no dedicated CLI command for token removal.