# How to Configure a GitHub Token for the GitHub Channel in Agent Reach

> Securely configure your GitHub token in config.yaml using the Agent Reach CLI. Grant full read-write access to private repos and manage issues effortlessly with this quick guide.

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

---

**Store your GitHub token securely in `~/.agent-reach/config.yaml` using the built-in CLI command to enable full read-write access to private repositories and issue management.**

Agent Reach is an open-source automation framework that integrates with GitHub through a dedicated channel. To configure a GitHub token for the GitHub channel, you use the `Config` class to persist credentials locally and the `GitHubChannel` class to authenticate API requests. This setup allows the tool to escalate from read-only public repository access to full private repository management, issue creation, and pull request workflows.

## Understanding the GitHub Channel Architecture

The **GitHub channel** implementation resides in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py). The `GitHubChannel` class provides two operational modes determined by its `check()` method.

When the channel initializes, it probes the local `gh` CLI (the official GitHub command-line tool) to verify installation and authentication status. If the CLI reports an authenticated session, the channel enables full functionality. Without authentication, the channel falls back to read-only mode and surfaces a warning to the user.

## Configuration Storage and Security Model

Token persistence is handled by the **Config** class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When you configure a GitHub token for the GitHub channel, the `set("github_token", value)` method writes the key to `~/.agent-reach/config.yaml` with **600 permissions** (owner-only read/write).

The security model ensures the token never leaves your local machine. The `to_dict()` method masks the token value when displaying configuration, and the runtime system excludes the token from all logs and public output.

## Step-by-Step Configuration Methods

### Using the CLI Command

The simplest way to configure a GitHub token for the GitHub channel is through the registered sub-command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1122-1124). This interface validates input and handles file permissions automatically.

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

```

Upon execution, the CLI invokes `config.set("github_token", value)` and prints a confirmation message. The token is immediately available for subsequent GitHub channel operations.

### Manual Configuration

You can also edit the configuration file directly. This is useful when migrating settings or using configuration management tools.

```bash
$EDITOR ~/.agent-reach/config.yaml

```

Add or update the following entry:

```yaml
github_token: ghp_YourGeneratedTokenHere

```

Ensure the file permissions remain restricted to your user:

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

```

### Verifying the Configuration

To confirm the token is stored correctly without exposing the full value, use the diagnostic command:

```bash
agent-reach doctor | grep "GitHub"

```

Expected output:

```

GitHub token: ghp_YourGe… (masked)

```

## Runtime Token Usage

When processing requests, the GitHub channel retrieves the token via `config.get("github_token")`. If present, the channel injects the `Authorization: token <TOKEN>` header into underlying `gh` CLI commands or direct API calls.

This authentication enables private repository access and write operations. The following Python snippet demonstrates how the channel internally passes the token to subprocess calls:

```python
import subprocess
import json
import os

token = os.getenv("GITHUB_TOKEN") or config.get("github_token")
result = subprocess.run(
    ["gh", "repo", "view", "your-private-org/private-repo", "--json", "name,description"],
    capture_output=True,
    text=True,
    env={**os.environ, "GITHUB_TOKEN": token},
)
print(json.loads(result.stdout))

```

Because the token is cached in the configuration, the `gh` CLI authenticates automatically without interactive prompts.

## Summary

- **Location**: Tokens are stored in `~/.agent-reach/config.yaml` via the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- **Security**: File permissions are set to 600, and tokens are masked in configuration displays and logs.
- **CLI Command**: Use `agent-reach configure github-token <TOKEN>` to persist credentials (implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)).
- **Channel Logic**: The `GitHubChannel` class in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) uses the `check()` method to verify `gh` CLI authentication and enable full access.
- **Runtime**: The token is retrieved via `config.get("github_token")` and injected as an `Authorization` header for API requests.

## Frequently Asked Questions

### Where is the GitHub token stored when I configure it?

The token is stored in the local YAML file at `~/.agent-reach/config.yaml` under the key `github_token`. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles the write operation with strict 600 permissions, ensuring only the file owner can read or modify the value.

### Can I use the GitHub channel without a token?

Yes, but with limitations. According to the `GitHubChannel.check()` method in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py), the channel will operate in read-only mode for public repositories if the `gh` CLI is not authenticated. To access private repositories or create issues and pull requests, you must configure a GitHub token for the GitHub channel.

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

Run `agent-reach doctor` and grep for "GitHub" in the output. The diagnostic tool calls the configuration's `to_dict()` method, which displays a masked version of the token (e.g., `ghp_YourGe…`). If the token is missing or the `gh` CLI is not authenticated, the check will report warnings regarding limited functionality.

### Is it safe to store my GitHub token in Agent Reach?

Yes. The implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) ensures the token never leaves your local machine. The file is created with 600 permissions, the token is excluded from logs, and the `to_dict()` method masks the value when displaying configuration. The token is only used to set the `GITHUB_TOKEN` environment variable for local `gh` CLI subprocess calls.