# Configure GitHub Personal Access Token for Agent Reach Private Repositories

> Securely configure your GitHub personal access token for Agent Reach to access private repositories. Follow simple steps to add your token and ensure seamless integration.

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

---

**To enable Agent Reach to access private GitHub repositories, run `agent-reach configure github-token <YOUR_TOKEN>` which stores the credential in `~/.agent-reach/config.yaml` under the `github_token` key.**

Agent Reach requires authentication to interact with private GitHub repositories. According to the Panniantong/Agent-Reach source code, the tool manages sensitive credentials through a local YAML configuration file and provides a dedicated CLI command to handle the GitHub personal access token securely.

## Where Agent Reach Stores GitHub Credentials

User-specific settings reside in `~/.agent-reach/config.yaml`. The **`github_token`** key stores the GitHub personal access token used for all private repository operations.

In [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config` class handles persistence. The `Config.set` method (lines 27-33) writes values to an in-memory dictionary, while `Config.save` (lines 49-66) flushes data to disk with **0600** permissions (read/write for owner only).

## Step-by-Step Configuration Guide

### Generate a GitHub Personal Access Token

Navigate to https://github.com/settings/tokens. Create a new token with a descriptive name.

Agent Reach does not require any special scopes for reading private repositories; a token with default settings (no scopes selected) works for basic read operations. Copy the generated token immediately, as GitHub displays it only once.

### Store the Token Using the CLI

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

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

```

The CLI confirms successful storage with the message "✅ GitHub token configured!"

### Verify the Configuration

Check the configuration file directly:

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

```

You should see the token stored under the `github_token` key:

```yaml
github_token: ghp_abcdefghijklmnopqrstuvwxyz1234

```

Run the health check to validate the token works:

```bash
agent-reach doctor

```

The GitHub section should report `ok` if the token is valid and the `gh` CLI is installed.

## How the Token Is Used Internally

When components need API access, they invoke `Config.get("github_token")` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-77). This method first checks the in-memory dictionary, then falls back to the **`GITHUB_TOKEN`** environment variable if the config file value is absent.

The `GitHubChannel` class in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-43) uses this token to authenticate via the `gh` CLI or direct API calls during health checks and repository operations.

## Alternative Configuration Methods

### Direct File Editing

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

```yaml
github_token: ghp_YourActualTokenHere

```

Ensure the file maintains **0600** permissions (readable only by the owner).

### Environment Variable Override

Set `GITHUB_TOKEN` in your shell to override the config file:

```bash
export GITHUB_TOKEN=ghp_YourActualTokenHere
agent-reach doctor

```

## Programmatic Access

For custom integrations, access the token via Python:

```python
from agent_reach.config import Config

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

print("Token prefix:", token[:8] + "...")  # Masked for safety

```

## Summary

- Agent Reach stores GitHub tokens in `~/.agent-reach/config.yaml` under the `github_token` key with restricted **0600** permissions
- Use **`agent-reach configure github-token <TOKEN>`** to set credentials securely via the CLI
- The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles storage while `Config.get` supports environment variable fallback
- The `GitHubChannel` class in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) consumes the token for API authentication
- Verify setup with **`agent-reach doctor`** to ensure private repository access works correctly

## Frequently Asked Questions

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

No. Agent Reach requires no special scopes for basic private repository access. A token generated with default settings (no scopes selected) works for read operations, as the tool primarily needs to read repository contents and metadata.

### Can I use an existing GitHub token?

Yes. Any valid GitHub personal access token can be configured using the `agent-reach configure github-token` command or by setting the `GITHUB_TOKEN` environment variable. The system accepts standard `ghp_` tokens without validation of specific scopes.

### Where does Agent Reach check if my token is working?

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 during the `agent-reach doctor` command. This health check verifies authentication via the `gh` CLI when available, or validates API accessibility through direct token usage.

### Is the token stored securely?

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) explicitly sets file permissions to **0600** (readable and writable only by the owner). The configuration file resides in your home directory under `.agent-reach/`, keeping the token isolated from other users on the system.