I work as a consultant, which means I’m constantly jumping into new projects—sometimes coding full-time, other times just reviewing code or doing a repository deep-dive. Every few months, I’m setting up a fresh Version Control System (VCS) config. Usually it’s GitHub, sometimes Bitbucket, and every now and then, GitLab makes an appearance.

So, here’s a simple guide to keep things smooth. I know there are plenty of tutorials out there, but I’m terrible at bookmarking, so I need one place I can reliably find. This guide covers managing multiple Git configs on the same machine, without breaking anything.

SSH or HTTPS? SSH!

Most VCS platforms offer the option to authenticate via SSH or HTTPS. With HTTPS, Git doesn’t store your credentials by default, meaning you have to enter them every time you interact with a remote repository (clone, push, pull)—not ideal. SSH is more secure and convenient since, once set up, it works seamlessly in the background.

Rule of Thumb: One SSH keypair per Git Config

Using one SSH keypair per VCS profile is the best practice. It keeps things organized and secure. Let’s get started.

Steps

Note: You can repeat the following steps for all your VCS accounts to manage multiple profiles effortlessly.

1. Generate a New SSH Key

First, create a new SSH key for your profile:

ssh-keygen -t ed25519 -C "email@example.com" -f ~/.ssh/id_<profile>

• -t ed25519: This generates an Ed25519 key, which is faster and more secure than RSA.
• -C "email@example.com": The comment to help you remember which email this key is associated with.
• -f ~/.ssh/id_: Specify the file name for the key, so it’s easier to identify later.

If you prefer to use RSA:

ssh-keygen -t rsa -b 4096 -C "email@example.com" -f ~/.ssh/id_<profile>

Passphrase: Add It for Extra Security

During the key generation process, you’ll be prompted to add a passphrase. It’s highly recommended to use one as it adds a layer of security to your private key.

To check your newly created key files, run:

ls -la ~/.ssh

You should see both the private key id_<profile> and the public key id_<profile>.pub.

2. Add the SSH Key to the SSH Agent

Next, we need to ensure that ssh-agent remembers your passphrase so you don’t have to enter it every time.

First, ensure ssh-agent is running:

eval "$(ssh-agent -s)"

Now, add your key to the agent:

ssh-add --apple-use-keychain ~/.ssh/id_<profile>

The --apple-use-keychain flag (macOS only) adds the key to your keychain for easier access. If you’re on Linux or Windows, you may omit this option.

3. Configure the SSH Settings

Now, let’s create or modify your SSH config file to organize your keys:

touch ~/.ssh/config

Open the file and add the following:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_<profile>

This ensures that your SSH key is automatically added to the agent and remembered.

4. Copy the Public SSH Key to Your VCS

Copy your public key to your clipboard:

pbcopy < ~/.ssh/id_<profile>.pub

Now, add this key to your respective VCS platform:

• Add SSH key to Github
• Add SSH key to BitBucket
• Add SSH key to Gitlab

5. Set Up Git Configurations for Multiple Profiles

To manage multiple VCS profiles (clients, personal, etc.), create separate .gitconfig files for each profile, ensuring your repositories use the right settings.

Assume your project directory is structured like this:

/code/
    |__client_a/
    |__client_b/

Create separate Git configuration files for each profile:

/code/
|__profile_a/
    |_.gitconfig.profile_a
|__profile_b/
    |_.gitconfig.profile_b

In each .gitconfig.<profile>, set up the details for the corresponding profile:

# ~/code/<profile>/.gitconfig.<profile>

[user]
  email = profile_email@example.com
  name = Your Name

[github]
  user = "username_for_account"

[core]
  sshCommand = "ssh -i ~/.ssh/id_<profile>"

sshCommand = "ssh -i ~/.ssh/id_<profile>": This command tells Git which SSH key to use for this specific profile.

6. Configure the Global Git Settings

Finally, configure your global .gitconfig to include these individual profile settings based on the directory:

# ~/.gitconfig

[includeIf "gitdir:~/code/profile_a/"]
  path = ~/code/profile_a/.gitconfig.profile_a

[includeIf "gitdir:~/code/profile_b/"]
  path = ~/code/profile_b/.gitconfig.profile_b

[core]
  excludesfile = ~/.gitignore # applies globally

The includeIf directive tells Git to apply the corresponding .gitconfig profile settings when you’re working in the specified directory. It ensures each repository is using the correct SSH key and user details.

Conclusion

Hopefully, following this guide, you’ll have a streamlined, secure setup for managing multiple Git profiles on the same machine. No more re-entering credentials or worrying about mixing up keys across projects.