GitHub Account Sync

What it does

When you switch profiles, gitswitch can automatically call gh auth switch to sync your GitHub CLI account.

gitswitch work
# Switches git identity AND GitHub CLI account

Why you need this

The GitHub CLI (gh) manages separate authentication from git:

• gh auth switch changes which GitHub account gh CLI commands operate under
• It does NOT change your git commit identity
• If you forget to switch in gh, you might create a PR or issue from the wrong account

gitswitch can handle both in one command.

Setup

Add profile with GitHub username

gitswitch add work "Alice" alice@company.com \
  --gh-user alice-work

List GitHub accounts

gh auth status

Shows all authenticated GitHub accounts.

gh auth login

Authenticate a new GitHub account with gh.

How it works

When you switch to a profile with a GitHub username, gitswitch runs:

gh auth switch --user alice-work

Behavior

Important: GitHub sync is best-effort:

• If gh is not installed, the switch is ignored
• If the account is not authenticated, the switch fails gracefully
• Your git config always switches even if gh fails

Example:

gitswitch work
# Even if `gh auth switch` fails, your git identity is now 'work'

Verify account

After switching:

gh auth status
# Shows the active account

Multiple GitHub accounts

If you have multiple GitHub accounts:

# Personal account
gitswitch add personal "Alice" alice@gmail.com \
  --gh-user alice \
  --ssh-key ~/.ssh/id_personal

# Work account
gitswitch add work "Alice" alice@company.com \
  --gh-user alice-work \
  --ssh-key ~/.ssh/id_work

Switching profiles switches both git and GitHub CLI.

Troubleshooting

gh auth switch fails

If gh auth switch fails:

1. Is gh installed?
2. Is the account authenticated?

# List authenticated accounts
gh auth status

# Login to account if needed
gh auth login --with-token < token.txt

3. Is the username correct?

# Check your GitHub username
gh auth status

GitHub CLI account and git identity mismatch

If your GitHub account differs from git config:

# Check active account
gh auth status

# Check git identity
git config --global user.email

They can be different — gh commands use the GitHub account, commits use git config.

If you want them in sync:

# Manually switch git (if gitswitch didn't)
gitswitch work

# Manually switch GitHub (if gh auth switch failed)
gh auth switch --user alice-work

Disabling GitHub sync

If you don’t want GitHub sync for a profile:

gitswitch add work "Alice" alice@company.com
# Don't pass --gh-user flag

Now switching to work changes only git identity, not GitHub CLI account.

Next steps

→ Identity Awareness
→ Shell Integration
→ Quick Start