# How to Configure GitHub Token for Private Repos in Agent-Reach

> Configure your GitHub token in Agent-Reach to gain authenticated access to private repositories. Learn how to set up your token quickly and securely for seamless integration.

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

---

**Store your GitHub Personal Access Token using `agent-reach configure github-token <TOKEN>` to enable authenticated access to private repositories.**

Agent-Reach stores user-specific settings in a YAML configuration file located at `~/.agent-reach/config.yaml`. The `github_token` key within this file controls access to private GitHub repositories. This guide explains how to set up this token using the CLI or manual configuration, based on the actual source code implementation in the `Panniantong/Agent-Reach` repository.

## Storing the GitHub Token

You have two methods for configuring your GitHub token: using the interactive CLI (recommended) or editing the configuration file directly.

### Using the CLI (Recommended)

The `configure` subcommand in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103) handles token storage securely. Run the following command and replace `<YOUR_TOKEN>` with your GitHub Personal Access Token:

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

```

The CLI calls `config.set("github_token", value)` internally, which writes the token to `~/.agent-reach/config.yaml`. After execution, you will see the confirmation: "✅ GitHub token configured!"

### Manual Configuration (Advanced)

You can directly edit the configuration file at `~/.agent-reach/config.yaml`. The file uses YAML format with the `github_token` key:

```yaml
github_token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

According to the `Config.save` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 49-66), this file is created with permissions `0600` (read/write for owner only), ensuring your token remains private.

## How the Configuration Works Internally

Understanding the internal mechanics helps with troubleshooting and advanced use cases.

### The Config Class

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages the `github_token` key. When you run the configure command, the `Config.set` method (lines 27-33) updates the in-memory configuration and triggers a save to disk.

### Environment Variable Fallback

If the token is not found in the configuration file, `Config.get` (lines 69-77) automatically checks for an environment variable named `GITHUB_TOKEN` (uppercase). This allows temporary overrides without modifying the config file:

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

```

### GitHub Channel Integration

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 for authentication. During the health check (`GitHubChannel.check`), the channel validates the token against the GitHub API, either through the authenticated `gh` CLI or direct API calls using the stored token.

## Verifying Private Repository Access

After configuration, verify that Agent-Reach can communicate with private repositories.

### Using the Doctor Command

Run the built-in diagnostic tool to confirm your token works:

```bash
agent-reach doctor

```

The output includes a **GitHub** section. A valid token shows `ok`, while a missing `gh` CLI but valid token shows `warn` (since the API remains accessible).

### Programmatic Validation

You can verify token access programmatically using the `Config` class:

```python
from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")

if token:
    print(f"GitHub token configured: {token[:8]}...")
else:
    print("No GitHub token found")

```

This reads the token from the configuration file or environment variable, following the fallback logic defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

## Security and File Permissions

Agent-Reach prioritizes token security through filesystem permissions. The `Config.save` method explicitly sets file permissions to `0600` (owner read/write only) when writing `~/.agent-reach/config.yaml`. This prevents other users on the system from reading your GitHub credentials.

For additional security, use a fine-grained Personal Access Token with minimal scopes. Agent-Reach only requires read access to repositories; the default "no scope" token works for basic private repo access, though you may need `repo` scope for specific operations.

## Summary

- **Store tokens** using `agent-reach configure github-token <TOKEN>` which writes to `~/.agent-reach/config.yaml` via `Config.set`.
- **File location** is `~/.agent-reach/config.yaml` with the key `github_token`, secured with `0600` permissions.
- **Fallback support** allows using the `GITHUB_TOKEN` environment variable if the config file lacks the key.
- **Verification** occurs through `agent-reach doctor` or the `GitHubChannel.check` method in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py).

## Frequently Asked Questions

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

Agent-Reach stores the token in `~/.agent-reach/config.yaml` under 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) creates this file with strict `0600` permissions, ensuring only your user account can read the sensitive 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) checks for the `GITHUB_TOKEN` environment variable (uppercase) as a fallback. If `github_token` is not set in the YAML file, Agent-Reach automatically uses the environment variable value.

### What GitHub token scopes does Agent-Reach require?

Agent-Reach works with a default "no scope" token for basic private repository access. However, if you encounter permission errors, generate a token with the `repo` scope at https://github.com/settings/tokens to ensure full read access to private repositories.

### How do I verify my token is working correctly?

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). This validates the token against the GitHub API. Alternatively, check `~/.agent-reach/config.yaml` directly to confirm the `github_token` key exists and contains your token value.