# How to Set Up GitHub Token Authentication for Private Repositories with Agent Reach

> Learn how to set up GitHub token authentication for private repositories with Agent Reach. Securely connect to your private repos using a PAT and the agent-reach CLI.

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

---

**Agent Reach authenticates to private GitHub repositories using a Personal Access Token stored in `~/.agent-reach/config.yaml` under the `github_token` key, which you can configure via the `agent-reach configure github-token` CLI command.**

The open-source **Panniantong/Agent-Reach** project provides a unified interface for AI agents to interact with various channels, including private GitHub repositories. Setting up GitHub token authentication is essential for enabling read operations on private repos, and the configuration is handled through a secure local YAML file and a simple CLI interface.

## Where Agent Reach Stores Authentication Credentials

Agent Reach persists user-specific settings in a YAML configuration file located at `~/.agent-reach/config.yaml`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages this file, ensuring sensitive tokens are written with restrictive permissions.

The specific key for GitHub authentication is **`github_token`**. When you run the configuration command, the CLI invokes `Config.set("github_token", value)` (lines 27-33 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)), which writes the token to disk with `0600` permissions (read/write for owner only) via the `Config.save` method.

## Configure Your GitHub Personal Access Token

### Generate a PAT on GitHub

Before configuring Agent Reach, create a Personal Access Token on GitHub:

1. Navigate to **GitHub Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)** or visit `https://github.com/settings/tokens`.
2. Click **Generate new token** and select the appropriate token type.
3. **Leave all scopes unchecked**—Agent Reach does not require any special permissions to read private repositories; a token with no scopes works for basic repository access.
4. Copy the generated token immediately (GitHub displays it only once).

### Store the Token Using the CLI

The recommended method for storing your token is through the Agent Reach CLI. In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103), the parser handles the `configure` sub-command with the `github-token` argument and persists the value:

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

```

Upon successful execution, the CLI outputs: `✅ GitHub token configured!`

### Verify the Configuration File

Confirm the token was written correctly by inspecting the configuration file:

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

```

You should see the entry:

```yaml
github_token: ghp_xxxxxxxxxxxxxxxxxxxx

```

The file permissions are automatically set to `0600` to prevent unauthorized access.

## How Agent Reach Uses the Token

When the `GitHubChannel` needs to authenticate API requests, it retrieves the token through the `Config.get("github_token")` method (lines 69-77 in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)). This method implements a fallback hierarchy:

1. First checks the in-memory configuration dictionary
2. Then checks the environment variable `GITHUB_TOKEN` (uppercase)
3. Finally reads from the `~/.agent-reach/config.yaml` file

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 configuration during the health check process, verifying that the token is present and functional.

## Code Examples

### Configure via CLI

```bash

# Set the token interactively

agent-reach configure github-token ghp_abcdefghijklmnopqrstuvwxyz1234

# Verify the configuration

agent-reach doctor

```

### Access Token Programmatically

```python
from agent_reach.config import Config

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

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

```

### Manual Configuration File Editing

For advanced users who prefer direct file manipulation:

```yaml

# ~/.agent-reach/config.yaml

github_token: ghp_your_personal_access_token_here

```

Ensure the file permissions remain secure:

```bash
chmod 600 ~/.agent-reach/config.yaml

```

## Summary

- Agent Reach stores GitHub tokens in `~/.agent-reach/config.yaml` under the `github_token` key, managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- Use the command `agent-reach configure github-token <TOKEN>` to securely store credentials via the CLI.
- The configuration file is created with `0600` permissions to protect sensitive data.
- The `GitHubChannel` retrieves tokens via `Config.get("github_token")`, which supports environment variable fallbacks.
- Verify your setup with `agent-reach doctor` to confirm the GitHub channel reports healthy authentication status.

## Frequently Asked Questions

### What permissions does the GitHub token need for Agent Reach?

Agent Reach requires **no special scopes** to access private repositories. When generating your Personal Access Token on GitHub, you can leave all permission scopes unchecked. The token only needs basic repository read access, which is granted by default to tokens with no scopes selected.

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

Yes. According to the `Config.get` implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-77), Agent Reach checks for the `GITHUB_TOKEN` environment variable (uppercase) before falling back to the configuration file. This allows you to export tokens in CI/CD environments without writing to disk: `export GITHUB_TOKEN=ghp_xxxxxxxx`.

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

Run the diagnostic command `agent-reach doctor`. This executes the `GitHubChannel.check` method in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py), which validates that your token can authenticate with GitHub's API. If the token is valid, the output shows `ok` for the GitHub channel; if `gh` CLI is missing but the token is valid, it may show `warn` while remaining functional.

### Is the GitHub token stored securely by Agent Reach?

Yes. The `Config.save` method explicitly sets file permissions to `0600` (read and write for owner only) when writing `~/.agent-reach/config.yaml`. This prevents other users on the system from reading your authentication credentials, following Unix security best practices for sensitive configuration files.