SSH Setup

In order to access a git service using git, you will need to create an ssh key pair and install it on the git service.

The following examples will use gitlab as an example. Other services may be slightly different in some respects, but the overall theory should be similar.

Generating a SSH key

If you have not created a ssh key, use the following command to generate one (do this from your workstation so you will have the key available for use after the training):

$ cd ~/.ssh
$ ssh-keygen -t ed25519 -f id_ed25519_git

Some git hosting services may not yet support ed25519 keys. If the service you want to use does not support ed25519 keys, generate your key pair with the following:

$ ssh-keygen -t rsa -b 4096 -f id_rsa_git

Note

ECC (Eliptic Curve Cryptography) keys are much smaller and less computationally intensive than RSA keys, while being equally or more secure. For RSA keys to become more secure, you need to increase the number of bits which increases both the size and the computational load to use the key. Also, it appears that the future of cryptographic keys will likely be ECC. With that in mind, you should probably start using ed25519 keys when ever possible.

Reference:

Next, will you need to upload the public key (id_ed25519_git.pub) to the git repository hosting service.

Note

It is not required to name your key id_ed25519_git. Doing so only makes it clear to you what the key is used for. Any ssh key that you have already created can be used if you do not want to create another key. The only requirement is that a public key identifying you is installed on the hosting service’s server.

Note

There is nothing stopping you from using the same ssh key for every server you need access to, but best practices dictate that you should generate a different key for each server.

References:

Upload Public Key to gitlab

Login to gitlab and install the contents of the public key file using this page:

Test the key installation with (you should get your user name in the response instead of mine):

$ ssh -i ~/.ssh/id_ed25519_git git@gitlab.com
Enter passphrase for key '/home/troth/.ssh/id_ed25519_git':
PTY allocation request failed on channel 0
Welcome to GitLab, Theodore A. Roth!
Connection to gitlab.com closed.

Upload Public Key to github

Login to github and install the contents of the public key file using this page:

Test the key installation with:

$ ssh -i ~/.ssh/id_ed25519_git git@github.com
Enter passphrase for key '/home/troth/.ssh/id_ed25519_git':
PTY allocation request failed on channel 0
Hi troth! You've successfully authenticated, but GitHub does not provide shell access.
Connection to github.com closed.

Upload Public Key to bitbucket

Login to bitbucket and install the contents of the public key file using this page:

Test the key installation with:

$ ssh -i ~/.ssh/id_ed25519_git git@bitbucket.org
Enter passphrase for key '/home/troth/.ssh/id_ed25519_git':
PTY allocation request failed on channel 0
logged in as taroth.

You can use git or hg to connect to Bitbucket. Shell access is disabled.
Connection to bitbucket.org closed.

Adding an SSH Config Entry

You can make your life a little easier by adding an entry for the hosting service to your ~/.ssh/config file.

Add the following to your ~/.ssh/config file on your workstation:

$ cat >>~/.ssh/config <<EOF
Host gitlab
     User git
     Hostname gitlab.com
     Port 22
     Identityfile ~/.ssh/id_ed25519_git
EOF

Add similar entries for github or bitbucket should you wish to use those services.

With this configuration entry in place, you can now just use the following to test access to the service:

$ ssh gitlab
Enter passphrase for key '/home/troth/.ssh/keys/id_ed25519_git':
PTY allocation request failed on channel 0
Welcome to GitLab, Theodore A. Roth!
Connection to gitlab.com closed.

SSH Agent

When pushing and pulling from a remote git repository, git will use ssh to both authenticate you to the server and to encrypt the data passed between your system and the server.

Each time a git command communicates with the remote server, you will be asked to provide the pass phrase for your ssh key. This can get annoying and tedious quite quickly. There are two ways to avoid having to type a pass phrase every time:

  • Generate an ssh key with no pass phrase. This is simple to do but is bad practice. If someone obtains your private key they can immediately use it to access your git repositories on the server (e.g. they could insert malicious code, delete branches, or any number of bad operations). Even worse, if you use the same key for many servers, they would have access to all of them. It is not recommended to use ssh keys with no pass phrase.

  • Use ssh-agent. This tool will unlock a key by having you enter the pass phrase for the key once and continue to use that unlocked key for the duration of the session, or until the ssh-agent process is terminated.

On many systems, a ssh-agent is automatically started when you login to the desktop. You can check if a ssh-agent is running with the following:

$ env | grep SSH_AGENT
SSH_AGENT_PID=25422

If SSH_AGENT_PID is set, then ssh-agent is likely running. You can verify with the following:

$ ps ax | grep 'ssh-agen[t]'
25422 ?        Ss     0:00 ssh-agent
26904 ?        Ss     0:00 ssh-agent

Notice that on my system, I have two instances of ssh-agent running and one matches the SSH_AGENT_PID value. There is nothing wrong with running multiple instances of ssh-agent. One could have been started automatically when you logged in on the desktop and another could have been started by you via an ssh login from a remote system.

If you need to start the ssh-agent, the following is the easiest way (assuming you are running in a bash shell):

$ eval $(ssh-agent)
Agent pid 26904

which is equivalent to this:

$ ssh-agent
SSH_AUTH_SOCK=/tmp/ssh-zkl1xk7JkO7W/agent.26903; export SSH_AUTH_SOCK;
SSH_AGENT_PID=26904; export SSH_AGENT_PID;
echo Agent pid 26904;
$ SSH_AUTH_SOCK=/tmp/ssh-zkl1xk7JkO7W/agent.26903; export SSH_AUTH_SOCK;
$ SSH_AGENT_PID=26904; export SSH_AGENT_PID;
$ echo Agent pid 26904;
Agent pid 26904

Note

Starting ssh-agent from the command line will make that instance of ssh-agent accessible only from within that shell session, not from other shells you have started from your desktop environment. You could export the variables as done above in other shells to share the ssh-agent with other shells currently running.

Once you have an instance of ssh-agent running, you will need to add keys to the agent:

$ ssh-add ~/.ssh/id_ed25519_gitlab
Enter passphrase for /home/troth/.ssh/id_ed25519_gitlab:
Identity added: /home/troth/.ssh/id_ed25519_gitlab (troth@example)

You can view which keys have been added to the agent with:

$ ssh-add -l
256 SHA256:WDXiVEhLF7Lt053cqvTXpxb62u+4Uv9e/sYnd9bEYno troth@example (ED25519)

Now any git commands (accessing the remote server via ssh) run from this shell or session will no longer need to have you enter the pass phrase to unlock the ssh key.

Of course, the ssh-agent is useful beyond the realm of git. Use it for any ssh or scp operations.