Skip to content

Latest commit

 

History

History
80 lines (57 loc) · 3.58 KB

reference.md

File metadata and controls

80 lines (57 loc) · 3.58 KB

Configuration and routing

Configuration lives at ~/.config/gh-context/config.json. Use GH_CONTEXT_CONFIG for another file, or XDG_CONFIG_HOME for another config root. An optional real_gh absolute path selects the native GitHub CLI executable.

Account selection

The first matching rule wins:

  1. GH_CONTEXT explicitly selects a configured profile.
  2. A repository owner rule matches the resolved command target.
  3. git config github.account matches a configured account on that host.
  4. The most specific directory rule matches the current working directory.
  5. Git's URL-scoped credential.username matches a configured account.
  6. The configured default for the target host applies.

An explicit repository or URL takes priority over GH_REPO and the checkout's origin when identifying the target. Supported target forms include --repo/-R, gh repo view|clone|fork|create|delete|archive|unarchive|edit|sync OWNER/REPO, PR/issue/run/release URLs, and REST gh api repos/OWNER/REPO/... endpoints. --hostname, full enterprise URLs, and SSH/HTTPS origins identify the host. Conflicting explicit hosts fail before authentication.

GraphQL bodies, search filters, shell aliases, and extension-specific arguments are not parsed for account selection. Run those commands from the appropriate checkout or set a profile explicitly:

GH_CONTEXT=work gh-context api graphql -f query='query { viewer { login } }'

Add enterprise profiles using their actual hostname and configure a default or owner rule for that host. Hosted enterprise domains ending in .ghe.com use GH_TOKEN; other enterprise hosts use GH_ENTERPRISE_TOKEN.

Explicit token environment variables retain native gh precedence and override stored credentials. status reports that token source without displaying its value; status --check reports the identity actually authenticated by the server.

Wrapper

gh-context wrap installs a small launcher at ~/.local/bin/gh. Put that directory before native gh in PATH; run rehash or hash -r in existing shells if needed. Use --bin-dir PATH to choose another directory. Existing executables and symlinks are preserved. Native CLI discovery skips gh-context's managed launcher.

Account management (gh auth ...), configuration, aliases, and help retain native semantics. In particular, gh auth status shows native gh's global selection; gh context shows this wrapper's per-command selection. Native gh status continues to work as usual.

For Git processes started by gh, such as clones and PR checkouts, an HTTPS credential helper is supplied only in the child environment. Ordinary git commands, commit identity, signing, and SSH keys are unchanged.

To remove the wrapper and package:

gh-context unwrap
uv tool uninstall gh-context

Configuration and stored credentials are preserved. The tool never logs in, switches accounts, retries under another identity, or grants repository permissions.

Coding agents

The optional agent skill explains routing and access diagnostics. Copy or link its directory into your agent's personal skill directory, such as ~/.codex/skills/ or ~/.claude/skills/, without replacing an existing skill. Routing itself is deterministic Python code and works without it.

GitHub MCP connections and browser sessions authenticate independently. This tool routes local CLI processes only; remote/cloud agents need their own installation and credentials. No account configuration is discovered from untrusted repository files: configure rules in your local config or Git configuration deliberately.