---
status: accepted
---

# GitHub access is a direct REST client; credentials resolve flag → env → store → `gh auth token`

Alchemy talks to GitHub through its own REST client, never by shelling out to `gh` porcelain at runtime — a long-running shell binary subprocessing per verb means output-parsing across gh versions, and gh's own keyring auth can silently act as a different identity than the one configured. But requiring a hand-minted PAT per user is antithetical to alchemy's minimal-setup goal when most operators already have `gh` authenticated. So `gh` is demoted to a **token source**: resolution order is `--token` flag → env var → Windows Credential Manager → `gh auth token` (invoked once at bind, re-invoked on 401). In practice the tail serves the frictionless 90% case; the PAT path remains for headless nodes and CI, optional but never required.

## Consequences

Zero-setup bind for gh-authenticated users, while ROADMAP's speced resolution order is preserved (extended by one tail entry). Config records token *provenance*, never the token itself — a gh re-auth is picked up on the next resolve. Writes attribute to whatever account the resolved token belongs to; acceptable single-operator, revisited when multi-user identity arrives. Org-owned repos require the org to permit the token's OAuth app (gh CLI is usually approved) — the bind-time validation handshake surfaces this explicitly rather than letting first-write fail.