# How to Configure Private GitHub Access in Agent Reach

> Configure private GitHub access for Agent Reach using a PAT or GITHUB_TOKEN environment variable. Seamlessly integrate Agent Reach with your private repositories and the GitHub CLI.

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

---

**Agent Reach authenticates to private GitHub repositories using a Personal Access Token (PAT) stored in `~/.agent-reach/config.yaml` or via the `GITHUB_TOKEN` environment variable, enabling the GitHub CLI (gh) to access private repos on your behalf.**

To enable AI agents to interact with private source code, **Panniantong/Agent-Reach** requires explicit authentication credentials. Configuring private GitHub access in Agent Reach involves supplying a GitHub Personal Access Token that the tool persists securely and passes to the underlying GitHub CLI.

## Understanding the Authentication Flow

Agent Reach does not implement its own GitHub API client. Instead, it wraps the **GitHub CLI (gh)** and manages authentication tokens on your behalf. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) defines a required feature called `github_token` (line 29), which the system checks before executing any repository operations.

When properly configured, Agent Reach writes your token to its local YAML configuration file and ensures the `gh` binary uses these credentials when cloning, reading, or analyzing private repositories.

## Step-by-Step Configuration

### Generate a GitHub Personal Access Token

Before configuring Agent Reach, create a token with appropriate permissions:

1. Navigate to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) or Fine-grained tokens.
2. Enable the **`repo`** scope for full control of private repositories.
3. Add `read:org` if you need to access organization-level repository information.
4. Copy the generated token (format: `ghp_...`).

### Store the Token via Agent Reach CLI

Use the built-in configuration command to persist the token:

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

```

This command invokes `config.set("github_token", value)` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (line 1123), writing the credential to `~/.agent-reach/config.yaml`. The token is stored with standard filesystem permissions.

### Verify Private Repository Access

Confirm the GitHub channel is active using the diagnostic command:

```bash
agent-reach doctor

```

For JSON output inspection:

```bash
agent-reach doctor --json | jq '.github'

# Expected output: { "status": "ok", "details": "gh CLI + token" }

```

With a valid token, `gh repo view owner/private-repo` executes successfully through Agent Reach.

## Alternative: Environment Variable Authentication

If you prefer not to write credentials to disk, Agent Reach supports runtime authentication via environment variables. The `Config.get()` method checks for the **`GITHUB_TOKEN`** environment variable after inspecting the configuration file.

Set the variable in your shell:

```bash
export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
agent-reach doctor  # Detects token via env var without file persistence

```

This approach is ideal for CI/CD pipelines or temporary access scenarios where you want to avoid persisting secrets in `~/.agent-reach/config.yaml`.

## Technical Implementation Details

The authentication system relies on three core components:

- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**: Implements the `Config` class that defines the `github_token` requirement and handles YAML persistence.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Provides the `configure github-token` interface that writes to the configuration object.
- **`~/.agent-reach/config.yaml`**: Stores the actual token value (masked in CLI output).

When the `doctor` command reports the GitHub channel as *ready*, any subsequent `agent-reach` invocation that calls `gh` (such as `gh issue list` or `gh repo view`) automatically inherits the stored credentials.

## Summary

- **Agent Reach uses the GitHub CLI (gh)** for all repository operations, requiring a Personal Access Token for private repos.
- **Store tokens via** `agent-reach configure github-token <token>` to write to `~/.agent-reach/config.yaml` as implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Minimum required scope** is `repo` for private repository access.
- **Environment variable fallback** allows using `GITHUB_TOKEN` instead of file-based configuration.
- **Verify setup** with `agent-reach doctor` to ensure the GitHub channel status reports "ok".

## Frequently Asked Questions

### What GitHub token scopes are required for Agent Reach?

The token must include the **`repo`** scope to grant full control of private repositories. If your workflows involve organization-level data or team mentions, add the `read:org` scope. Fine-grained personal access tokens require read access to repository contents and metadata.

### Is it safe to store my GitHub token in Agent Reach's configuration file?

Agent Reach stores the token in `~/.agent-reach/config.yaml` with standard filesystem permissions. While this is convenient for persistent access, users with strict security requirements should use the **`GITHUB_TOKEN`** environment variable method instead, which leaves no persistent credential on disk between sessions.

### Why does Agent Reach use the GitHub CLI instead of direct API calls?

Agent Reach wraps the **GitHub CLI (gh)** to leverage its built-in authentication handling, caching, and error management. This design, implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), ensures compatibility with existing GitHub authentication methods while minimizing credential handling complexity in the Agent Reach codebase.

### How do I troubleshoot "GitHub channel not ready" errors?

Run `agent-reach doctor` to diagnose connectivity. If the GitHub check fails, verify that your token is valid (not expired), has the `repo` scope, and is either stored in the config file via `agent-reach configure github-token` or exported as `GITHUB_TOKEN`. Ensure the `gh` CLI is installed and accessible in your system PATH.