# How to Manually Configure a GitHub Token for Private Repository Access in Agent Reach

> Learn how to manually configure a GitHub token for private repository access in Agent Reach. Securely set your token via CLI or environment variable for seamless integration.

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

---

**Store your GitHub Personal Access Token in `~/.agent-reach/config.yaml` under the `github_token` key using the CLI command `agent-reach configure github-token <TOKEN>`, or set the `GITHUB_TOKEN` environment variable for automatic detection.**

Agent Reach requires authentication to access private GitHub repositories. According to the Panniantong/Agent-Reach source code, the tool centralizes credentials in a YAML configuration file and supports multiple configuration methods including CLI commands, manual file editing, and environment variables.

## Create a GitHub Personal Access Token

Before configuring Agent Reach, generate a token with appropriate permissions. Navigate to https://github.com/settings/tokens and create a new token with a descriptive name. You do not need to assign any specific scopes for basic private repository access; a token with no scope works for reading private repositories.

Copy the generated token immediately, as GitHub displays it only once during creation.

## Configure the Token in Agent Reach

The configuration system is implemented in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), where the `Config` class manages persistence and retrieval of the `github_token` value.

### Method 1: CLI Configuration (Recommended)

Use the `configure` subcommand to securely store the token. 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 calls `Config.set("github_token", value)`.

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

```

The command writes to `~/.agent-reach/config.yaml` and prints "✅ GitHub token configured!" upon success. The `Config.save` method creates the file with `0600` permissions (owner read/write only) to prevent unauthorized access.

### Method 2: Manual Configuration File Editing

Edit the YAML file directly at `~/.agent-reach/config.yaml`:

```yaml
github_token: ghp_YourTokenHere

```

The `Config.save` method (lines 49-66 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) ensures the file maintains secure permissions when modified.

### Method 3: Environment Variable

Set the `GITHUB_TOKEN` environment variable. The `Config.get` method (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) checks for the uppercase environment variable as a fallback when the config file value is absent.

```bash
export GITHUB_TOKEN=ghp_YourTokenHere

```

This method is useful for CI/CD pipelines or temporary configurations where you do not want to persist credentials to disk.

## Verify the Configuration

Run the health check to confirm authentication:

```bash
agent-reach doctor

```

The `GitHubChannel.check` method (lines 19-43 in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py)) validates the token against the GitHub API. A successful check reports `ok` or `warn` (if the `gh` CLI is missing but the token remains valid for direct API calls).

## Programmatic Access

Access the token in Python using the `Config` class:

```python
from agent_reach.config import Config

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

```

The `Config.get` method first checks the in-memory dictionary, then falls back to the `GITHUB_TOKEN` environment variable if the configuration file does not contain the key.

## Summary

- Agent Reach stores GitHub tokens in `~/.agent-reach/config.yaml` under the `github_token` key
- Use `agent-reach configure github-token <TOKEN>` for secure CLI-based configuration with automatic `0600` file permissions
- The `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) checks for the `GITHUB_TOKEN` environment variable (uppercase) as a fallback
- Verify authentication 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)
- No specific GitHub scopes are required for the token to access private repositories

## Frequently Asked Questions

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

Agent Reach stores the token in `~/.agent-reach/config.yaml` as 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) (lines 49-66) creates this file with `0600` permissions, ensuring only the file owner can read or write the credential.

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

Yes. The `Config.get` method (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) checks for the `GITHUB_TOKEN` environment variable (uppercase) if the value is not found in the configuration file. This allows temporary or CI/CD-based authentication without modifying persistent files.

### What permissions does my GitHub token need?

No specific scopes are required for basic private repository access. When generating the token at https://github.com/settings/tokens, you can leave all scopes unchecked. The token only needs standard read permissions to access repository contents and metadata through the GitHub API.

### How do I verify that 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 against the GitHub API. If the token is valid, the check reports `ok` or `warn` if the `gh` CLI is missing but the token remains functional for direct API calls.