Understanding SSH Host Aliases ("Pseudo-Domains") for Git Multi-Account

The Core Concept

When you see github.com-work in an SSH config or git remote URL, that is NOT a real domain name. It's an SSH host alias (sometimes called a "pseudo-domain") — a label that only exists in your ~/.ssh/config file. It never hits DNS.

# This is an ALIAS — "github.com-work" is a made-up name
Host github.com-work
    HostName github.com    # ← the REAL server to connect to
    User git
    IdentityFile ~/.ssh/id_ed25519_work  # ← the key to use

When SSH sees github.com-work, it:

1. Looks it up in ~/.ssh/config
2. Finds the real hostname (github.com)
3. Uses the specified key (id_ed25519_work)
4. Connects to github.com authenticating with that specific key

Why This Is Necessary

GitHub identifies which account you are by your SSH key, not by the URL.

Without aliases, SSH picks a key automatically (usually the default or first one offered). If you have multiple GitHub accounts, the default key maps to only one of them — the others will fail.

The alias trick forces SSH to use a specific key for a specific "nickname", even though all nicknames point to the same real server (github.com).

The Full Flow: What Happens When You git push

git push origin main
  │
  ▼
git reads remote URL: git@github.com-work:org/repo.git
  │
  ▼
git invokes SSH: ssh git@github.com-work
  │
  ▼
SSH reads ~/.ssh/config → finds "Host github.com-work"
  │
  ▼
SSH connects to HostName: github.com (the REAL server)
  with IdentityFile: ~/.ssh/id_ed25519_work
  │
  ▼
GitHub receives the SSH key → identifies you as "work-user"
  │
  ▼
GitHub checks: does "work-user" have access to org/repo?
  │
  ▼
Push proceeds (or fails with "Repository not found" — see Troubleshooting below)

As a Mermaid Diagram

sequenceDiagram
    participant Git as git push
    participant SSH as SSH client
    participant Config as ~/.ssh/config
    participant GH as github.com

    Git->>SSH: connect to github.com-work
    SSH->>Config: lookup "Host github.com-work"
    Config-->>SSH: HostName=github.com, Key=id_ed25519_work
    SSH->>GH: connect to github.com using id_ed25519_work
    GH-->>SSH: authenticated as work-user
    SSH-->>Git: connection established, push proceeds

Loading

The Mental Model

Think of it as giving each GitHub account a nickname that SSH understands:

Alias (nickname)	Real server	SSH key used	GitHub account
github.com	github.com	id_ed25519_personal	personal-user
github.com-work	github.com	id_ed25519_work	work-user
github.com-oss	github.com	id_rsa_oss	oss-user

All three connect to the same server. The alias is just a routing label.

Common Source of Confusion

GitHub's web UI shows clone URLs like:

git@github.com:org/repo.git

This uses bare github.com — which means your default SSH key. If your default key belongs to personal-user but the repo belongs to work-user, the push will fail.

The fix: Replace github.com with your SSH alias in the remote URL:

# Wrong (uses default key):
git@github.com:org/repo.git

# Correct (uses work key via alias):
git@github.com-work:org/repo.git

How This Connects to the gh CLI

This setup involves two separate authentication layers that must both be configured:

flowchart TB
    subgraph "Layer 1: API Operations — gh CLI"
        A["gh-work pr create"] --> B["GH_CONFIG_DIR=~/.config/gh-work"]
        B --> C["OAuth token for work-user"]
        C --> D["GitHub REST/GraphQL API"]
    end

    subgraph "Layer 2: Git Transport — SSH"
        E["git push origin main"] --> F["Remote: git@github.com-work:org/repo"]
        F --> G["~/.ssh/config → Host github.com-work"]
        G --> H["~/.ssh/id_ed25519_work"]
        H --> I["GitHub SSH server"]
    end

    D -.- |"Both must authenticate as the SAME account"| I

Loading

• gh-work alias (via GH_CONFIG_DIR) controls which account the gh CLI uses for API calls (PRs, issues, releases, etc.)
• github.com-work alias (via ~/.ssh/config) controls which SSH key git uses for transport (push, pull, fetch, clone)

If you configure one but not the other, some operations work and others fail in confusing ways:

Misconfiguration	Symptom
Wrong GH_CONFIG_DIR	gh commands create PRs/issues on wrong account (or 404)
Wrong remote URL (bare github.com)	git push fails with "Repository not found"
Both wrong	Everything fails

Troubleshooting

"ERROR: Repository not found" — The Misleading Error

If you get this error when pushing to a repo you know exists, the most likely cause is your SSH key mapped to the wrong account.

GitHub returns "not found" (instead of "access denied") for security — it prevents leaking whether private repos exist. But this means wrong SSH key looks identical to wrong repo URL.

Debugging Commands

# Which GitHub user does this SSH alias authenticate as?
ssh -T git@github.com-ACCOUNT
# Expected: "Hi USERNAME! You've successfully authenticated..."

# Which SSH key is being offered? (verbose mode)
ssh -vT git@github.com-ACCOUNT 2>&1 | grep "Offering public key"

# What remote URL does this repo use?
git remote -v
# Check: does it show github.com-ACCOUNT or bare github.com?

# Which gh account is active for this config dir?
GH_CONFIG_DIR=~/.config/gh-ACCOUNT gh auth status

Quick Diagnosis Flowchart

git push fails with "Repository not found"
  │
  ├─ Run: ssh -T git@github.com-ACCOUNT
  │   ├─ Shows wrong username → SSH key/config issue
  │   └─ Shows correct username → repo permissions issue
  │
  └─ Run: git remote -v
      ├─ Shows bare github.com → fix with: git remote set-url origin git@github.com-ACCOUNT:org/repo.git
      └─ Shows github.com-ACCOUNT → SSH config or key issue