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

> Securely configure your GitHub token for Panniantong/Agent-Reach repository access. Learn the simple command to set your token in agent-reach config yaml.

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

---

**Agent Reach stores your GitHub Personal Access Token in `~/.agent-reach/config.yaml` under the `github_token` key, which you can set via the CLI command `agent-reach configure github-token <TOKEN>`.**

To access private GitHub repositories, Agent Reach requires authentication via a Personal Access Token (PAT). This guide walks you through generating the token, storing it securely in the Agent Reach configuration system, and verifying that the `GitHubChannel` can authenticate with GitHub's API.

## Generate a GitHub Personal Access Token

Agent Reach requires a GitHub Personal Access Token to read repository contents and metadata. You do **not** need any special scopes for basic operations; the default "no scope" token works for reading private repositories.

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. Leave all scopes unchecked (no scope is required for read access).
5. Click **Generate token** and copy the value immediately (it displays only once).

## Store the Token Using the Agent Reach CLI

The recommended method for configuring your GitHub token uses the Agent Reach CLI, which securely writes the value to your user configuration file.

Run the following command, replacing `<TOKEN>` with your copied Personal Access Token:

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

```

The CLI confirms successful configuration with the message: `✅ GitHub token configured!`

Internally, this command invokes the `Config.set` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 27-33), which validates and stores the key-value pair. The CLI argument parser in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1101-1103) specifically handles the `github-token` argument and maps it to the internal `github_token` configuration key.

## Verify the Configuration

Confirm that your token was saved correctly by inspecting the configuration file:

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

```

You should see output similar to:

```yaml
github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

```

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

## How Agent Reach Uses the Token

Agent Reach retrieves the GitHub token at runtime using the `Config.get` method defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 69-77). This method implements a fallback hierarchy:

1. First checks the in-memory configuration dictionary for the key `github_token`.
2. If not found, falls back to the environment variable `GITHUB_TOKEN` (uppercase).
3. Returns `None` if neither source provides the token.

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) utilizes this token during its health check routine (`GitHubChannel.check`). The channel can leverage the authenticated `gh` CLI if installed, or use the token directly for API calls to private repositories.

## Alternative Configuration Methods

### Direct File Editing

You can manually edit the configuration file instead of using the CLI:

```bash
mkdir -p ~/.agent-reach
echo "github_token: ghp_YOUR_TOKEN_HERE" > ~/.agent-reach/config.yaml
chmod 600 ~/.agent-reach/config.yaml

```

### Environment Variable

For CI/CD pipelines or temporary access, set the `GITHUB_TOKEN` environment variable:

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

```

## Verify Repository Access

Test your configuration by running the health check command:

```bash
agent-reach doctor

```

The output includes a **GitHub** section. If the token is valid and the `gh` CLI is installed, the status reports `ok`. If `gh` is missing but the token is valid, you may see a `warn` status, though the token remains usable for direct API calls.

## Summary

- **Location**: Agent Reach stores the GitHub token in `~/.agent-reach/config.yaml` under the key `github_token`.
- **CLI Command**: Use `agent-reach configure github-token <TOKEN>` to set the token securely with `0600` file permissions.
- **Source Files**: Configuration logic resides in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 27-33 and 69-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).
- **Fallback**: The system checks the `GITHUB_TOKEN` environment variable if the config file entry is absent.
- **Verification**: Run `agent-reach doctor` to confirm the `GitHubChannel` can authenticate successfully.

## Frequently Asked Questions

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

Agent Reach stores the token in a YAML configuration file at `~/.agent-reach/config.yaml` under the key `github_token`. The file is created with restrictive permissions (`0600`) by the `Config.save` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to prevent unauthorized access.

### What GitHub token scopes are required for Agent Reach?

Agent Reach does **not** require any specific scopes for reading private repositories. A Personal Access Token with **no scopes** selected (the default) provides sufficient access for the `GitHubChannel` to read repository contents and metadata through the GitHub API.

### 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 the `GITHUB_TOKEN` environment variable (uppercase) if the `github_token` key is not present in the configuration file. This is useful for CI/CD environments where writing to disk is undesirable.

### How do I troubleshoot GitHub authentication errors in Agent Reach?

Run `agent-reach doctor` to execute the health check in [`agent_reach/channels/github.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/github.py) (lines 19-43). Verify that `~/.agent-reach/config.yaml` contains the correct `github_token` value, or ensure the `GITHUB_TOKEN` environment variable is exported. If using the `gh` CLI, confirm it is authenticated by running `gh auth status`.