# How to Configure GitHub Token Authentication in Agent Reach > Learn how to configure GitHub token authentication for Agent Reach. This guide details the simple steps to enable repository modifications using your Personal Access Token. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-07-14 --- **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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (line 1124), the CLI handles the `configure github-token` sub-command and validates the input before storage. ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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: ```bash 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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: ```bash 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 ` 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (line 1124) will guide you through re-entering credentials if the stored token is invalid.