Skip to content

Instantly share code, notes, and snippets.

@BolderLearnerTechSchool

BolderLearnerTechSchool/configure_your_macBook_to_use_more_than_one_gitHub_account.md

Last active December 21, 2025 14:35
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save BolderLearnerTechSchool/3d09b8301a9a956542846860d005f0ab to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save BolderLearnerTechSchool/3d09b8301a9a956542846860d005f0ab to your computer and use it in GitHub Desktop.
Download ZIP
Learn how to use more than one GitHub account in your macbook
Raw
configure_your_macBook_to_use_more_than_one_gitHub_account.md

Configure Your MacBook To Use More Than One GitHub Account

If you have more than one GitHub account, you want to make sure you are working with the correct one. One thing we really like here about GitHub is the multi-account feature they added.

GitHub multiuser account feature

Instead of having to create browser profiles to access your account, this feature allows you to move between accounts freely. So, how can you configure your macbook to use the correct account?

The assumption we are making here is that you are already familiar with setting up git and GitHub. If not, check the official GitHub Documentation.

Table Of Contents

Step 1: Create Two SSH Keys

SSH keys are a form of public‑key cryptography used to prove your identity to a remote service (like GitHub) without typing a password. When you create an SSH keypair, you get two related files:

  • 1. Private key (keep secret)

    • Stored on your computer (e.g., in ~/.ssh/). ◦ Used to cryptographically sign a challenge during login/auth. ◦ Anyone who gets this file can impersonate you (so permissions matter).

  • 2. Public key (safe to share)

    • This is derived from the private key.
    • You upload this to GitHub (GitHub stores it on your account).
    • The public key cannot be used to derive the private key.

How authentication works (conceptually)

When you run a git command over SSH (clone, fetch, push), GitHub does roughly this:

  1. Your computer says: “I want to connect as git over SSH.”

  2. GitHub sends a random challenge.

  3. Your SSH client uses your private key to sign the challenge.

  4. GitHub verifies the signature using the public key it has on file.

  5. If the signature matches, GitHub knows: “This is the owner of that public key.”

    No password is exchanged.

Why SSH keys are great for “two GitHub accounts”

You can create one key per account, upload each public key to the corresponding GitHub account, and then configure SSH to choose the correct key depending on which “host alias” you use (later via ~/.ssh/config). Step 1 (key generation) sets you up for that clean separation.

Step 1.1: Create the SSH folder

Run:

mkdir -p ~/.ssh

mkdir, short for 'make directory', creates the hidden folder .ssh. The preceding ~ will create this hidden folder in your home directory. The ~/.ssh is the folder where SSH-related files typically live (keys, config, known_hosts). If you are curious what the -p flag does, it creates parent directories without throwing an error of one already exist.

Examples

  • If ~/.ssh does not exist:
    • mkdir -p ~/.ssh creates it.
  • If ~/.ssh already exists:
    • mkdir -p ~/.ssh does nothing and exits successfully.
  • Without -p, you’d get an error if it already exists:
    • mkdir ~/.ssh → File exists (error)

Using -p allows you to create nested folders as seen in this example:

mkdir -p ~/projects/tutorials/github

This creates ~/projects, then ~/projects/tutorials, then ~/projects/tutorials/github if they don’t already exist—one command.

Step 1.2: Update permissions

Run:

chmod 700 ~/.ssh

This command allows you, and no one else, to have read/write/access permission to the ~/.ssh folder. chmod means 'change mode' while the 700 is an octal permission code that means:

Digit Who Permission
7 owner (you) read (4) + write (2) + execute (1) = 7
0 group no permissions
0 others no permissions

Why the directory needs “execute”

For directories, “execute” doesn’t mean “run a program”. It means permission to enter/traverse the directory and access items inside it. So:

  • Directory read: you can list filenames (ls)
  • Directory write: you can create/delete/rename files inside
  • Directory execute: you can cd into it and access files within (subject to file permissions)

Why this is important for SSH

SSH is intentionally strict. If your .ssh directory or keys are too open (e.g., readable by others), SSH may refuse to use them to protect you from accidental exposure.

Examples

  • Secure (recommended):
    • chmod 700 ~/.ssh
  • Too open (bad):
    • chmod 755 ~/.ssh would allow other users on the machine to list/enter the directory (not good for private keys).
  • Slightly less strict but still common:
    • chmod 750 ~/.ssh gives your group some access (not recommended unless you have a reason).

Step 1.3.1: Generate Keypair For The First Account

Run this to generate a keypair for your first GitHub account (we shall call it personal):

ssh-keygen -t ed25519 -C "you_personal_email@example.com" -f ~/.ssh/id_ed25519_github_personal

This generates your first SSH keypair (for your personal GitHub account). To understand how a key is generated, see the following:

  • ssh-keygen: The key generation tool that comes with OpenSSH on macOS
  • -t ed25519: Chooses the algorithm type Ed25519:
    • It’s modern, secure, fast, and commonly recommended for SSH today.
    • It produces a small key and strong security.
  • -C "you_personal_email@example.com": Adds a comment label inside the public key.
    • This is mainly for humans (and for distinguishing keys in places like GitHub’s UI).
    • It does not control where the key is used.
    • It does not affect cryptographic security.
    • You can put any label here (email, machine name, “personal key”, etc.).
  • -f ~/.ssh/id_ed25519_github_personal: Sets the output filename (the base name). This will create:
    • ~/.ssh/id_ed25519_github_personal (private key)
    • ~/.ssh/id_ed25519_github_personal.pub (public key)

ssh-keygen will typically prompt you for:

  • A passphrase (optional). If you set one, you can later store it in Keychain/ssh-agent for convenience.

Step 1.3.2: Generate Keypair For The Second Account

Run:

ssh-keygen -t ed25519 -C "you_work_email@example.com" -f ~/.ssh/id_ed25519_github_work

This repeats the same process, but creates a second keypair with a different filename so it won’t overwrite the first key. It will create:

  • ~/.ssh/id_ed25519_github_work (private key)
  • ~/.ssh/id_ed25519_github_work.pub (public key)

Why the filenames matter

If you reused the default filename (like ~/.ssh/id_ed25519) twice, the second run would overwrite the first keypair. Using distinct filenames is what enables the “two accounts” setup cleanly.

Step 1.4: Confirm SSH Keys Have Been Generated

After generating keys, you need to confirm that the SSH files exist. Run this command:

ls -l ~/.ssh

You should see both keys and both .pub files.

In the gist Configure Your Computer To Use More Than One GitHub Account, you saw the use of ssh-keygen -t rsa -b 4096 -C "your-email-address" to generate SSH keys. Above, we have introduced ssh-keygen -t ed25519 -C "you_work_email@example.com" -f ~/.ssh/id_ed25519_github_work

What is the difference? (you may want to know)

Both commands generate an SSH keypair, but they use different cryptography and slightly different defaults.

ssh-keygen -t ed25519 -C "you_work_email@example.com" -f ~/.ssh/id_ed25519_github_work creates an Ed25519 key, which is a modern SSH key type. It tends to be faster and smaller than RSA, and it’s a great default for GitHub today. Because it includes -f ~/.ssh/id_ed25519_github_work, it also writes the key to a specific filename, which is important in a two-account setup so you don’t overwrite another key.

ssh-keygen -t rsa -b 4096 -C "your-email-address" creates an RSA key with a 4096-bit size. RSA is older but extremely widely supported, so it can be useful if you need maximum compatibility with older SSH systems. Since this command does not include -f, ssh-keygen will prompt you for where to save the key (often suggesting a default like ~/.ssh/id_rsa), which can be inconvenient in a multi-key setup unless you explicitly choose a unique filename.

In short: • Ed25519: modern, smaller/faster, great default for GitHub. • RSA 4096: very compatible, but larger/slower; be careful to name the output file when you have multiple keys.

Step 2: Ensure ssh-agent is running and keys load automatically

Step 1 created your key files on disk. Step 2 makes them pleasant to use day-to-day by ensuring you won’t be repeatedly prompted for passphrases and that SSH can quickly find the correct keys.

What is ssh-agent and why do we need it?

ssh-agent is a background process that holds decrypted private keys in memory for your login session.

  • If your private key has a passphrase, the key is encrypted on disk.
  • The first time you use it, SSH needs the passphrase to decrypt it.
  • After you add the key to ssh-agent, you typically enter the passphrase once, and the agent reuses it for subsequent SSH connections.

On macOS, you can also store the passphrase in Keychain, which allows keys to be reloaded automatically across sessions (depending on configuration). What does “load automatically” mean? It means that after you’ve set things up:

  • you don’t have to run ssh-add ... every time you open a new terminal (or after reboot), and/or
  • you aren’t prompted for the passphrase every time you git fetch/git push.

Exactly how “automatic” it is depends on:

  • whether you set a passphrase, and
  • whether you enable Keychain integration (--apple-use-keychain and UseKeychain yes in ~/.ssh/config).

Step 2.1 — Create/edit ~/.ssh/config (placeholder for now)

In Step 1, you learnt how to create the ~/ssh folder, which we said hosts all your SSH-related files. In this step, we are going to create a new empty file called config inside ~/.ssh. Why does this file matter?

  • ~/.ssh/config is the per-user SSH client configuration file. It controls things like:
    • which key file to use for a connection,
    • whether to add keys to the agent,
    • and (on macOS) whether to use Keychain.

If the file doesn’t exist yet, run:

touch ~/.ssh/config       # creates an empty file
chmod 600 ~/.ssh/config   # user permission

The 600 octal permission prevents other users on the machine from reading/modifying your SSH settings, and it satisfies SSH’s security checks (SSH may ignore configs/keys if permissions are too open). Only you can read and edit the file; nobody else can access it.

Digit Who Permission
6 owner read (4) + write (2) = 6
0 group no permissions
0 others no permissions

Step 2.2 — Add keys to the agent and store passphrases in Keychain

At this point you have two private keys saved on disk under ~/.ssh/. If those keys are protected with passphrases (recommended), you don’t want to re-type the passphrase every time you run git fetch or git push.

This step loads each private key into ssh-agent (a background process that remembers decrypted keys for your session) and, on macOS, can store the passphrase in Keychain so it can be re-used securely later.

Step 2.2.1: Add your personal key

Run:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519_github_personal
  • ssh-add registers a private key with ssh-agent
  • --apple-use-keychain tells macOS to save the key’s passphrase in Keychain (if the key has one)
  • You may be prompted for the key’s passphrase once (Keychain can prevent repeated prompts). If the key has no passphrase, it will typically just add it silently (or with a short confirmation).

Step 2.2.2: Add your work key

Run:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519_github_work

Same purpose as above, but for your second GitHub identity. Keeping one key per account avoids confusion and makes it easy to control which account is used per repo.

Step 2.2.3: Verify the keys are loaded

Run:

ssh-add -l

-l means “list”. You should see two entries (one for each key: key type eg ID25519, a fingerprint and a comment, often the -C email you used or the filename). If you see “The agent has no identities.”, it means no keys are currently loaded (you’d re-run the ssh-add ... commands).

After this step, SSH can use the keys without asking for the passphrase every time and both identities are available for use.

Step 3: Configure ~/.ssh/config with two GitHub “hosts”

In this step, you will set up SSH so it automatically chooses the right private key depending on whether you are working with your personal GitHub account or your work GitHub account. The key idea is simple:

  • Both of my GitHub accounts live on the same real server: github.com
  • But SSH lets me create host aliases (nicknames) like github-personal and github-work
  • Each alias can still point to the same HostName (github.com), while using a different IdentityFile (SSH key)

So later, when you run git commands, the remote URL you will use determines which key gets used:

  • git@github-personal:... → SSH uses my personal key
  • git@github-work:... → SSH uses my work key

3.1 Create or edit the SSH config file

Open ~/.ssh/config in a text editor by running:

nano ~/.ssh/config # I am using the nano text editor

Add this in the file that just opened:

# Personal GitHub
Host github-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github_personal
  IdentitiesOnly yes
  AddKeysToAgent yes
  UseKeychain yes

# Work GitHub
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github_work
  IdentitiesOnly yes
  AddKeysToAgent yes
  UseKeychain yes

What does each line mean?

  • Host github-personal / Host github-work: These define SSH host aliases.

    • They are not real DNS names.
    • They are labels used only by your SSH client to match settings.
    • You will use them in Git remote URLs later.

  • HostName github.com: This tells SSH: “When someone connects to github-personal, the real destination is github.com.” So:

    • Alias: github-personal
    • Real host: github.com

  • User git:

    • GitHub’s SSH endpoint expects the SSH username to be git.
    • This is normal for GitHub SSH URLs and does not represent your GitHub login name.

  • IdentityFile ...: This is the most important line for the “two accounts” setup.

    • For github-personal, SSH uses ~/.ssh/id_ed25519_github_personal

    • For github-work, SSH uses ~/.ssh/id_ed25519_github_work

      This is what prevents accidentally authenticating to the wrong account.

  • IdentitiesOnly yes: This tells SSH:

    • “Only use the key(s) explicitly specified by IdentityFile for this host.”
    • Don’t try a bunch of other keys you might have loaded in your agent.

    This avoids confusing “wrong account” situations caused by SSH offering some other key first.

  • AddKeysToAgent yes: This tells SSH:

    • If it uses this key and it’s not already in ssh-agent, add it automatically.

      This helps reduce how often you need to run ssh-add manually.

  • UseKeychain yes (macOS): This enables macOS Keychain integration so that:

    • if your key has a passphrase, macOS can store it in Keychain
    • future SSH uses can be non-interactive (no repeated passphrase prompts)

Once done, press control + X to exit nano and type y (for 'yes') when prompted on your way out.

Step 3.2 Lock down file permissions

After editing, make sure the permissions are strict:

chmod 600 ~/.ssh/config

Why this matters:

  • It prevents other users on the machine from reading/modifying your SSH rules.
  • SSH can ignore config files that are writable by others, because that’s a security risk.

Quick “how do I know this works?” check (optional but useful)

You can test each alias directly:

ssh -T github-personal
ssh -T github-work

Each should authenticate to GitHub, and in the output you should see it greet the corresponding GitHub username.

Step 4: Add each public key to the correct GitHub account

At this point, the SSH keys exist on your Mac, but GitHub doesn’t know about them yet. For GitHub to accept SSH logins from your machine, you need to upload each public key to the matching GitHub account.

A quick reminder of what you are uploading (and what your are not):

  • You upload the public key (.pub) to GitHub.
  • You never upload the private key (the file without .pub). The private key stays on my laptop.

Why you are doing this

When you later run git clone, git fetch, or git push over SSH:

  • Your Mac proves it owns the private key
  • GitHub checks that the corresponding public key is on your account
  • If they match, GitHub authenticates you without a password

Step 4.1 Copy the public keys from your Mac

Each keypair has two files:

  • Private key: ~/.ssh/id_ed25519_github_personal (keep secret)
  • Public key: ~/.ssh/id_ed25519_github_personal.pub (this is what you share)

Same pattern for the work key.

Option A (easy on macOS): copy to clipboard with pbcopy

Copy your personal public key:

pbcopy < ~/.ssh/id_ed25519_github_personal.pub

pbcopy copies text into the macOS clipboard. The < redirects the contents of the .pub file into pbcopy. After running it, you can paste the key directly into GitHub (See Step 4.2 below).

(Optional) sanity-check what you are copying

If you want to see the key printed in the terminal first run:

cat ~/.ssh/id_ed25519_github_personal.pub

A public key usually looks like a single long line starting with something like ssh-ed25519 ... and ending with the comment I used (often an email).

Step 4.2 Add the personal public key to your personal GitHub account

I sign into my personal GitHub account in the browser (if you haven't done so), then head over to the page Settings > SSH and GPG keys and click New SSH key.

  • Paste the key I just copied (from id_ed25519_github_personal.pub)
  • Give it a descriptive title, for example:
    • MacBook personal or MacBook - personal SSH key

Note: Do the same for the work SSH key.

Step 5: Use the right Host alias in your Git remotes

While working with repos, you need to take caution to use the right host alias in your remotes. While cloning, for example, you will do the following:

# personal repo
git clone git@github-personal:GitauHarrison/some-repo.git

# work repo
git clone git@github-work:BolderLearnerTechSchool/some-repo.git

Note that git@github-personal and git@github-work have been used as alias to point to github.com (the host) under the right accounts. The same thing applies when you are creating a repo for the first time.

Extra

Each commit you make to a repository on GitHub has an author and a committer. If you would like to learn more about this, see the original tutorial on non-macOS here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment