Introduction

Git is an essential tool used by data scientists, engineers and developers on a daily basis.

Developers may work on many projects at the same time. And each project might need a different git account to authenticate to the remote repository.

For example, you may need to access a GitLab account for client project A, but a separate GitHub account for internal company projects.

How can you switch between your git repositories without having to re-authenticate each time?

For a long time, I struggled to find a good solution. Until I invested 20 minutes understanding how to configure my git credentials.

It turns out, the solution involves understanding three things: SSH Keys, SSH config and git config.

In this post, I will describe how to use these three concepts to effortlessly manage your git profiles on a single machine.

1. SSH Keys

To clone and work on a private repository, you first need an authentication method.

There are two main methods for authenticating to a remote git repository: SSH keys or HTTPS.

HTTPS is more straight-forward and is often the default for many beginner tutorials. There is very little setup ā€“ provide your username and password and away you go.

However, SSH has several key benefits over HTTPS authentication, including:

  • No need to continually authenticate. HTTPS often requires you to input your password when switching accounts
  • Limited account access. If your SSH key is compromised, the attacker will not have full access to your git account. And you can easily revoke the SSH key without having to reset all your passwords
  • Expiry. You can set expiry dates on the SSH keys so they are only active for a certain amount of time. For example, setting your SSH key to only be active for the time you are on a project
  • Multiple git profiles can be seamlessly managed on the same machine via a config file

Taking the time to understand and use SSH keys will make your life easier in the long run. SSH keys are useful not just for git authentication but also for accessing virtual machines on cloud providers etc..

Note: you can set up personal access tokens for HTTPS authentication which provide some of the benefits of SSH keys (e.g. fine-grain access control and expiry dates).

Creating an SSH Key

To authenticate using SSH you first need to create a SSH key for each account. Generating a SSH key is done via the command line and is independent of the git hosting provider.

To generate an SSH key, open your terminal or command prompt and submit the following command. Change the comment to something meaningful for the git account you are setting up. For example, the relevant account email address for the account.

ssh-keygen -t ed25519 -C "<comment>"

The following output (or similar) will be displayed:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/jw/.ssh/id_ed25519):

You can either accept the default file name (id_ed25519) or you can specify a more meaningful name. I would recommend naming the file with the name of the account you are creating. For example, ‘work’, ‘personal’ or using some sort of differentiating alias. This will make it easier to keep track of the relevant SSH key when you set up multiple profiles.

Make sure you add the ~/.ssh/ (or C\Users\user\.ssh\ for Windows) prefix to your filename so the key is correctly added to the .ssh folder.

Once you select a file name and press Enter you will be asked to set a passphrase. You can opt to leave this empty by pressing enter, however, you should try and add a phrase for extra security in case your key gets compromised.

Upon confirming the passphrase, you will see confirmation that the key has been created and its location.

Note that two keys are generated by the ssh-keygen command: a public key, denoted by the file extension .pub and a private key with no file extension.

Add Public Key to your hosting provider’s account

Now that you have created a public and private SSH key, you need to add the public key (.pub) to your git account. This will allow you to link your git account to your local machine.

Instructions on how to add the public SSH key to your account can be found in the git repo hosting providers documentation:

The documentation may tell you to use pbcopy or some other command line tool to copy the SSH key contents to your clipboard. For example:

pbcopy < ~/.ssh/id_ed25519.pub

However, if you are having trouble with this command not working or do not already have pbcopy installed on your machine, you can always navigate to the file location in Finder/Windows Explorer and open it in a text editor and manually copy the file contents to the clipboard. Note, you should copy the entire contents of the file including the comment at the end of it.

Once you have copied the public key to your clipboard, paste the contents into the relevant section in your provider’s SSH settings (see provider’s documentation for details).

We have now created the SSH key and added it to the account. If you have multiple accounts with the same provider or different providers, you will need to repeat the steps above and create a unique pair of SSH keys (public and private) for each account.

Next, we get to the important part for managing multiple accounts - the SSH config file.

2. The SSH Config

The SSH config file allows you to specify the configuration rules for different hosts. This will dictate which SSH key is used for each account and allow us to create aliases when we have multiple accounts with the same providers.

There are a number of available SSH config options . Normally only HostName (provider’s main URL) and IdentityFile (location of relevant private SSH key) are required, however, you should check the git provider’s documentation to see if they require any other fields.

I normally also include AddKeysToAgent to automatically add the key to the ssh-agent which you would otherwise need to add manually using the ssh-add ~/.ssh/my_ssh_key_file command.

Note: If you have multiple accounts with the same provider, for example if you have a personal GitHub account and you also have a work account, you will need to specify a different Host entry in the config file.

The configuration file should be placed in the ~/.ssh/config file (C:\Users\user\.ssh\config for Windows). If it does not exist, you should create one.

An example ~/.ssh/config with multiple accounts is shown below:

## Example SSH config

# Personal GitHub account
Host github.com
    HostName github.com
    IdentityFile ~/.ssh/personal_gh
    AddKeysToAgent yes
    
# Work GitHub account
Host work.github.com
    HostName github.com
    IdentityFile ~/.ssh/work_gh
    AddKeysToAgent yes

# Client GitLab  account
Host gitlab.com
    HostName gitlab.com
    IdentityFile ~/.ssh/clientx_gl
    AddKeysToAgent yes

When you have multiple accounts with the same git hosting provider you need to specify a unique ‘Host’ name. (Note that the HostName field remains the same).

In the example config file above I have specified the Host for my work credentials to be work.github.com. With the current configuration, by default when cloning a repo from GitHub it would use my personal GitHub account as the Host is github.com. If I wanted to clone and work on a repo from GitHub using my work account, I would have to modify the git clone host to work.github.com. For example:

# Clone with personal credentials
git clone git@github.com:julian-west/asset_price_correlations.git

# Clone with work credentials
git clone git@work.github.com:julian-west/asset_price_correlations.git

Apart from this change to the repo address in the git clone command, we do not need to make any other changes or switch profiles. The SSH config will tell GitHub where the relevant SSH key can be found in order to complete the authentication.

Test the SSH key works

With the SSH config setup, we now need to verify that the SSH keys work as expected.

Open a terminal and run the following command (works on both Linux/MacOS and Windows). Replace the example.com with the value you have put for HostName in the SSH config file. For example git@gitlab.com

ssh -T git@example.com

If you have been successful in setting up the SSH key you will receive a welcome message - congratulations!

If you are unsuccessful, you can run the command in verbose mode in order to get more details on why your connection was not established.

# verbose mode
ssh -Tvvv git@example.com

Common issues with establishing a connection include miscopying the public SSH key to your git hosting provider or misspecifying the HostName address in the SSH config file.

The final piece of the puzzle for managing multiple accounts is git config.

3. The Git Config

It is important to correctly set your git configuration and profile for each repository you are working on to ensure your commit messages are accompanied by the correct username.

When working with multiple git accounts, if you only set a global git configuration username/email all of your commits will go through with that username. This can lead to accidently committing code to a project with the wrong username – i.e. your personal username could show up in a work project.

Depending on what you are working on, this might not be a big issue, however, there is an easy fix to ensure you always provide the right git profile with your code commits.

There are many different settings you can control using the git config command, such as the default branch name, your default editor for editing git commit messages and even the colour of various types of messages in your terminal. However, the most important to get right is the user.name and user.email settings.

These settings can be set at a global level or the local level. Many tutorials for getting started with git describe how to set defaults for these variables level using the --global flag. For example:

git config --global user.name engineeringfordatascience

This will set a global default for your user.name and user.email which will be used for all git repositories on your machine. Very few tutorials then mention how to override the global flag for repositories which use or require different git credentials.

This is a problem when you need to seamlessly use different git accounts on the same machine. Luckily, although not as widely mentioned, you can set these configurations at the local directory level using the --local flag, or using no flag at all.

git config user.name engineeringfordatascience
git config user.email contact@engineeringfordatascience.com

This command will override the global settings for the particular repository you are in and will save the information in the .git/config file in the same directory.

After cloning a repository and running the git config user.name command, all your commits to that repository will contain the correct username credentials, no matter which credentials are used at the global level.

Conclusion

In this tutorial we have described how to seamlessly manage authentication and credentials for multiple git profiles/accounts on the same machine.

This is particularly useful for developers and data scientists who work on multiple projects with multiple accounts.

After setting up SSH keys for your accounts, you can use the SSH config file and the local git config settings to set up your authentication and credentials once, and you can then forget about having to re-authenticate and remember which git profile is active.

Happy coding!

Other Relevant Articles

Further Reading