Developers who manage multiple GitHub accounts (personal, work, clients) face constant friction with gh CLI. While git handles multi-identity workflows well through SSH config, URL rewriting, and conditional includes, gh requires manual global switching via gh auth switch — a stateful operation that affects all repositories at once.

cd ~/work/project
gh auth switch --user work-account    # easy to forget!
gh pr create

cd ~/personal/project
gh auth switch --user personal-account  # forgot again...
gh pr create                            # created PR with wrong account 😠

The moment you have to think about switching, you're going to repeatedly forget to do it.

But even if you never forget, there's a deeper issue: gh auth switch is a global, stateful mutation. If you're working across multiple repositories concurrently — multiple terminal tabs, background scripts, IDE integrations — switching in one context silently affects all others. A global switch is fundamentally incompatible with concurrent multi-account usage.

References

• Blog post: Configuring SSH for Personal and Work GitHub Accounts
• Issue: Feature: Auto-switch accounts based on git config #12459 — Feature: Auto-switch accounts based on git config
• PR feat: auto-switch accounts based on git config github.account #12628 by @yuvrajangadsingh — auto-switch based on git config github.account
• PR Add repository-scoped auth mapping and repo-aware status #12681 by @awakecoding — repository-scoped auth mapping

Proposed Solution: Repository Auth Mapping (gh auth map)

The core idea is to add a built-in mapping mechanism within gh. Users define rules that map repository owners (or specific repositories) to authenticated accounts. gh resolves the current repository from git remotes and selects the correct account automatically — no manual switching required.

This is self-contained within gh, with no dependency on external git or SSH configuration, and works regardless of whether the repo was cloned over SSH or HTTPS.

Commands

gh auth map set <scope> --user <login>
gh auth map list [--hostname <host>]
gh auth map remove <scope>

Supported scopes

Matching priority: exact repo → owner wildcard → host active account. Environment token precedence (GH_TOKEN, GITHUB_TOKEN) is preserved.

Example

gh auth map set github.com/awakecoding/* --user awakecoding
gh auth map set github.com/Devolutions/* --user mamoreau-devolutions

From this point on:

cd ~/dev/awakecoding/MsRdpEx
gh pr list          # → uses 'awakecoding' automatically

cd ~/dev/Devolutions/Gateway
gh issue create     # → uses 'mamoreau-devolutions' automatically

No gh auth switch. No forgetting. No wrong-account PRs.

Enhanced gh auth status

gh auth status --active shows the effective account for the current repository, including the source of the selection (repository mapping, active host account, or environment token) — eliminating guesswork.

Why this approach

• Self-contained — managed entirely within gh, no external configuration needed
• Owner/repo-scoped — based on remote URL, not filesystem path
• Protocol-agnostic — works with both SSH and HTTPS remotes
• Transparent — existing gh commands work without modification
• Auditable — gh auth map list and gh auth status --active show what's configured and resolved
• Backward compatible — zero behavior change for users who don't configure mappings

Possible Extension: Git Config Integration

PR: #12628 by @yuvrajangadsingh | Issue: #12459 by @jayproulx

A complementary approach uses git config github.account (typically set via includeIf conditional includes) to let gh read the desired account from git's own configuration:

# ~/.gitconfig
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

# ~/.gitconfig-work
[github]
    account = work-username

This could be an additional resolution step: gh checks git config github.account first, and if the account is authenticated, uses it — otherwise falls through to mapping rules.

Strengths: familiar to includeIf users, directory-scoped (works even outside a repo).
Considerations: relies on external config, no built-in auditability, directory-based scoping may not cover all cases (e.g., repos from different orgs in the same parent directory).

Combined Resolution Chain

Both approaches can coexist:

GH_TOKEN / GITHUB_TOKEN (env vars)
  → git config github.account
    → gh auth map rules
      → active host account (existing behavior)

Questions for Discussion

1. Should gh own this natively? The mapping mechanism is self-contained and backward compatible.
2. Scoping model: Is owner/repo-based scoping the right primary model, or should directory-based (git config) be supported too?
3. Status visibility: Should gh auth status always show the effective account for the current repo context?
4. Command naming: Is gh auth map the right name, or would gh auth rule / gh auth account be clearer?
5. Scope of first PR: Should the initial implementation focus on gh auth map alone, with git config support as a follow-up?

I created PR #12681 as a working implementation — I've been using it locally and it eliminates the multi-account friction entirely. I'm happy to iterate on the design based on feedback.