How to Configure GitHub Token Authentication in Agent Reach

Agent Reach authenticates with GitHub by delegating to the official gh CLI, storing your Personal Access Token in ~/.agent-reach/config.yaml and automatically triggering gh auth login to enable repository modifications.

Agent Reach is an open-source automation framework that relies on the official GitHub CLI for all GitHub-related operations. While read-only actions on public repositories work without credentials, any repository modification—such as forking, creating issues, or opening pull requests—requires proper GitHub token authentication configured through the built-in CLI interface.

Configuring GitHub Token Authentication

Generate a Personal Access Token

Before configuring Agent Reach, generate a Personal Access Token (PAT) on GitHub with the required scopes. Navigate to GitHub Settings → Developer settings → Personal access tokens, and create a classic token with the repo scope (for repository-level writes) and read:org scope (for organization data access). These permissions allow Agent Reach to fork repositories, push branches, and interact with organization-level resources.

Store the Token via the Configure Command

Agent Reach provides a dedicated configuration command to persist your credentials securely. According to the implementation in agent_reach/cli.py (line 1124), the CLI handles the configure github-token sub-command and validates the input before storage.

agent-reach configure github-token ghp_XXXXXXXXXXXXXXXXXXXXXX

This command writes the token to ~/.agent-reach/config.yaml using the configuration manager defined in agent_reach/config.py, ensuring the credential persists across sessions.

Internal Authentication Flow

When you execute a GitHub operation requiring authentication, Agent Reach automatically forwards the stored token to gh auth login. The GitHub CLI then caches the authenticated session in its standard credential store at ~/.config/gh/hosts.yml, allowing subsequent Agent Reach commands to reuse the session without re-entering credentials.

Verify Your Setup

Run the diagnostic command to confirm that Agent Reach recognizes your GitHub token and the gh CLI integration is functional:

agent-reach doctor

A successful configuration displays a green checkmark for the GitHub integration, indicating that the token is valid and cached for subsequent API calls.

Performing Authenticated Operations

Once authenticated, you can perform write operations on repositories. For example, to fork a repository to your account:

agent-reach github fork https://github.com/owner/repo

If the token is omitted or invalid, the interactive prompt logic in agent_reach/cli.py (line 1124) automatically requests the token during the first GitHub command execution, preventing authentication failures from blocking your workflow.

Rotating or Updating Tokens

To replace an expired or compromised token, simply re-run the configuration command with your new PAT:

agent-reach configure github-token NEW_TOKEN

Agent Reach immediately updates ~/.agent-reach/config.yaml and refreshes the GitHub CLI authentication cache upon the next API invocation, as documented in the project’s setup guides.

Summary

• Agent Reach delegates GitHub authentication to the official gh CLI for maximum compatibility and security.
• Use agent-reach configure github-token <PAT> to store credentials in ~/.agent-reach/config.yaml.
• Required scopes are repo and read:org for full repository modification capabilities.
• The system automatically calls gh auth login and caches credentials in ~/.config/gh/hosts.yml.
• Verify configuration anytime using agent-reach doctor to ensure green status indicators.

Frequently Asked Questions

What scopes does my GitHub token need for Agent Reach?

Your Personal Access Token requires the repo scope for repository-level writes (including forking, creating issues, and pull requests) and the read:org scope to read organization membership data. These permissions allow Agent Reach to execute the full range of GitHub automation features as implemented in the source code.

Where does Agent Reach store my GitHub token?

Agent Reach stores the token in plain text within the YAML configuration file at ~/.agent-reach/config.yaml via agent_reach/config.py. However, the actual authentication session is encrypted and managed by the GitHub CLI, which caches credentials in ~/.config/gh/hosts.yml after the initial gh auth login handshake.

Can I use Agent Reach without a GitHub token?

You can perform read-only operations on public repositories without authentication, as the gh CLI supports anonymous access for viewing public data. However, any action that modifies a repository—such as forking, starring, or creating pull requests—requires a valid Personal Access Token configured through the configure github-token command.

How do I troubleshoot authentication failures?

Run agent-reach doctor to verify that your token is recognized and the GitHub CLI integration is functional. If authentication fails during command execution, check that your token has not expired and includes the required repo and read:org scopes. The interactive prompt in agent_reach/cli.py (line 1124) will guide you through re-entering credentials if the stored token is invalid.

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