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

> Learn how to configure GitHub tokens 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-07-01

---

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

To enable Agent Reach to access private GitHub repositories, you must provide a valid authentication token. This configuration step is essential for the `GitHubChannel` to authenticate API requests and perform repository operations. The following guide covers the complete setup process based on the actual implementation in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository.

## Setting Up the GitHub Personal Access Token

### Creating a Token on GitHub

Before configuring Agent Reach, generate a **Personal Access Token (PAT)** from your GitHub account settings.

1. Navigate to [https://github.com/settings/tokens](https://github.com/settings/tokens).
2. Click **"Generate new token (classic)"**.
3. Provide a descriptive name (e.g., "Agent-Reach-Access").
4. Set an expiration date according to your security policy.
5. Copy the generated token immediately (it is displayed only once).

### Required Permissions (Scopes)

For private repository access in Agent Reach, you **do not** need to select any specific scopes. The default "no scope" token provides sufficient permissions for reading private repositories. This minimal permission approach follows the principle of least privilege while allowing the `GitHubChannel` to perform necessary read and search operations.

## Configuring Agent Reach with Your Token

### Using the CLI (Recommended)

The most secure method to store your token is through the Agent Reach CLI, which writes the value to the configuration file with proper file permissions (`0600`).

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103), the argument parser handles the `github-token` sub-command and invokes `config.set("github_token", value)`:

```bash
agent-reach configure github-token <YOUR_TOKEN>

```

Upon successful execution, the CLI prints "✅ GitHub token configured!" and saves the value to `~/.agent-reach/config.yaml`. 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 is created with read/write permissions for the owner only, preventing unauthorized access.

### Environment Variable Fallback

Agent Reach supports an environment variable fallback mechanism. If the `github_token` key is not set in the configuration file, the `Config.get` method (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) automatically checks for the `GITHUB_TOKEN` environment variable (uppercase):

```bash
export GITHUB_TOKEN=ghp_your_token_here

```

This fallback is useful for CI/CD pipelines or temporary configurations where you prefer not to write credentials to disk.

### Manual Configuration (Advanced)

You can directly edit the YAML configuration file, though this is discouraged for production environments due to the risk of leaving tokens in shell history or clipboard.

Edit `~/.agent-reach/config.yaml`:

```yaml
github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

```

Ensure the file maintains `0600` permissions after editing to protect the sensitive credential.

## How Agent Reach Reads the Token

The configuration system uses a centralized `Config` class defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When the `GitHubChannel` needs to authenticate, it retrieves the token via `Config.get("github_token")`, which implements the following resolution order:

1. **In-memory dictionary**: Values set during the current session
2. **Configuration file**: The `github_token` entry in `~/.agent-reach/config.yaml`
3. **Environment variable**: `GITHUB_TOKEN` (converted to uppercase automatically)

The `Config.set` method (lines 27-33) handles the initial storage when using the CLI, while the `Config.get` method (lines 69-77) manages the retrieval logic with fallback support.

## Verifying the Configuration

After configuring your token, verify connectivity using the built-in health check. 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 that the token can authenticate with the GitHub API.

Run the diagnostic command:

```bash
agent-reach doctor

```

The output includes a **GitHub** section indicating the status:
- **`ok`**: The token is valid and the `gh` CLI is installed
- **`warn`**: The token is valid but the `gh` CLI is missing (Agent Reach will use direct API calls instead)
- **`error`**: The token is invalid or missing

## Summary

- **Storage location**: `~/.agent-reach/config.yaml` under the `github_token` key
- **CLI command**: `agent-reach configure github-token <TOKEN>` writes the value securely with `0600` permissions
- **Environment fallback**: `GITHUB_TOKEN` is checked if the config file entry is absent
- **Required permissions**: No special scopes required for private repository read access
- **Verification**: Use `agent-reach doctor` to confirm the `GitHubChannel` can authenticate
- **Source files**: Configuration logic in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 27-77), CLI handling in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103), and channel implementation 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

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

Agent Reach stores the token in a YAML configuration file located at `~/.agent-reach/config.yaml` under the key `github_token`. According to the source code in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the `Config.save` method 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 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-77) implements a fallback mechanism that checks for the `GITHUB_TOKEN` environment variable (uppercase) if the `github_token` key is not present in the configuration file. This is useful for ephemeral environments or when you want to avoid writing secrets to disk.

### What scopes does the GitHub token need for private repositories?

Agent Reach requires no specific scopes for accessing private repositories. A classic Personal Access Token with the default "no scope" setting provides sufficient permissions for reading repository contents and performing search operations. You do not need to enable `repo` scope unless you intend to perform write operations.

### How do I verify my GitHub token is working with Agent Reach?

Run `agent-reach doctor` to execute the health check implemented in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py). The `GitHubChannel.check` method (lines 19-43) validates the token against the GitHub API. If the token is valid, the output will show either `ok` (if the `gh` CLI is installed) or `warn` (if using direct API calls without the CLI).