How to Configure a GitHub Token for Agent Reach Repository Access

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.
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:

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 (lines 27-33), which validates and stores the key-value pair. The CLI argument parser in 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:

cat ~/.agent-reach/config.yaml

You should see output similar to:

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 (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 (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 (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:

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:

export GITHUB_TOKEN=ghp_YOUR_TOKEN_HERE
agent-reach doctor

Verify Repository Access

Test your configuration by running the health check command:

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 (lines 27-33 and 69-77), CLI handling in agent_reach/cli.py (lines 1101-1103), and channel implementation in 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 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 (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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}