This guide will go over setting up per-project deploy keys for use with GitHub, which allows a server which hosts multiple repositories to use a separate SSH key for each repository.
The only way to setup multiple GitHub repositories to use SSH to connect to GitHub is to attach an SSH key to your GitHub user account. Attaching the key to the user account makes it impossible to use per-project SSH keys, a best practice for servers that have multiple git repositories in use.
This problem can be mitigated by setting up a deploy server, but that can be overkill in many situations (and is an additional point of maintenance).
In this guide, we will use built-in capabilities of the ssh-agent to manage multiple SSH keys on a single machine, allowing us to use per-project deploy keys for multiple projects on the same server.
Check for existing keys
First, check for existing SSH keys:
$ ls -al ~/.ssh
The filenames of any public keys are usually one of the following:
If you don’t have any existing key pairs, proceed to creating new ones. If you do have existing key pairs, try to find out what they are used for and if you can remove them. It is not a good idea to have un-used SSH keys or SSH keys being used by unknown entities on your server.
Generate per-project SSH key pairs
After checking on the status of any existing keys, generate a new SSH key pair for the first repository to be managed by the server:
ssh-keygento generate a new key formatted how GitHub prefers them:
$ ssh-keygen -t rsa -b 4096 -C "firstname.lastname@example.org"
When prompted for a file in which to save the key, make sure to add the project’s name (or some sort of identifier) to the file name:
Enter a file in which to save the key (/Users/username/.ssh/id_rsa): /Users/username/.ssh/id_rsa_<projectname>
When prompted to enter a passphrase, enter one that you will remember (or be sure to put it in OnePassword/LastPass/etc.).
Add the new key to the ssh-agent:
$ ssh-add ~/.ssh/id_rsa_<projectname>
Repeat steps 1-4 for any additional projects that will have repositories on the server.
Create an SSH config file to manage the keys
.ssh directory, create a file called config:
$ touch ~/.ssh/config
Open the config file and add the following:
Host github-project1 HostName github.com User git IdentityFile /Users/username/.ssh/id_rsa_project1 Host github-project2 HostName github.com User git IdentityFile /Users/username/.ssh/id_rsa_project2
For example, if your username was bender and your two projects were bend_girder and drink_beer, the SSH config file would look like this:
Host github-bend_girder HostName github.com User git IdentityFile /Users/bender/.ssh/id_rsa_bend_girder Host github-drink_beer HostName github.com User git IdentityFile /Users/bender/.ssh/id_rsa_drink_beer