Goal

Add GitHub App support as an alternative to the current Personal Access Token (PAT) flow. App-based auth would centralize per-org credentials, give per-installation tokens, and better fit Archon's worktree + multi-codebase model.

This is a roadmap item — not in 0.3.11 scope. Filing now to consolidate the related auth issues that an App migration would touch.

Current state

Archon authenticates to GitHub via PAT (GH_TOKEN / GITHUB_TOKEN):

• The token is set via env var or ~/.archon/.env.
• The gh CLI uses it for gh pr, gh issue, gh release, etc.
• git clone and git fetch against private GitHub repos use it via the credential helper.
• Webhook signature verification uses a separate secret.

This works for individual users but breaks down for:

• Org repos requiring SSO sign-in on the PAT.
• Per-codebase token scoping (today the same PAT is used for everything).
• Worktree sync's git fetch subprocess inheriting auth differently than gh CLI calls.

Open issues this would partially or fully resolve

• rfc(auth): rethink per-codebase GitHub PAT injection — env vars are the wrong primitive #1467 — rfc(auth): rethink per-codebase GitHub PAT injection — env vars are the wrong primitive. App installations are scoped per-org or per-repo and produce short-lived installation tokens. Clean per-codebase scoping.
• bug(isolation/git): worktree sync fails 403 on org repos — per-codebase GH_TOKEN never reaches git fetch subprocess #1469 — bug(isolation/git): worktree sync fails 403 on org repos — per-codebase GH_TOKEN never reaches git fetch subprocess. App-issued tokens via the credential helper would be shared correctly across gh and git.
• Bash nodes don't inherit gh keyring auth — fresh-private-repo first runs fail silently #1476 — Bash nodes don't inherit gh keyring auth — fresh-private-repo first runs fail silently. App-based credentials would land in the system keychain consistently.

Rough scope

Big lift. Notes for whoever picks this up:

• New auth path in @archon/providers/... (or wherever GitHub auth lives — probably in adapters and workspace clone code).
• Webhook verification stays the same (signature secret independent of App).
• Setup wizard gains a "PAT or App?" branch (or "App-first, PAT as legacy fallback" if we go aggressive).
• Migration: existing users on PAT keep working. New users get App by default. Doc page covers swap-over.
• Need to register an Archon GitHub App in the org or per-installation; figure out distribution model.

Out of scope here

• The 0.3.11 setup overhaul (Setup overhaul: binary install primary, dead-simple wizard, archon doctor, embedded skill (v0.3.11) #1494) keeps PAT as the only documented option. App support comes later.
• GitLab/Gitea — community adapter territory; separate roadmap.

When

Post-0.3.11. Probably 0.4.x. No hard deadline; pick up when one of the linked issues becomes user-visible enough to escalate.