, ,

Troubleshooting gitolite SSH connection issues

We’re all agree that GitHub it’s pretty much the next best thing since sliced bread, but there will be times that we’ll need to host some repositories on our own server, and for that cases Gitolite it’s probably the best tool.

There are, however, several issues that you might find when trying to connect or creating an access for some user, and most likely they’ll be related to the SSH connection instead of gitolite itself, so here are a few tips to help you get around those issues.

Connect using the correct user

Ok, perhaps this it’s a bit obvious for most… but it certainly wasn’t for me the first time I used gitolite.

When you’re connecting through SSH, you’re probably typing something like

ssh your_user_name@server.com

right?

Well, with gitolite the “correct” user will always be the same for all users, so you’ll probably end up cloning a repo with something like

git clone git@server.com:your-repository.git

Check what repositories you can access

This also serves as a basic check to see if you’r public key it’s properly configured for access.

Instead of cloning or performing any git command on a repository, try to connect using SSH to the server with the “git” user, i.e.

ssh git@server.com

The server will reply with an informative message, like:

PTY allocation request failed on channel 0
hello {your_local_username}, this is gitolite 2.3-1 (Debian) running on git 1.8.3.2
the gitolite config gives you the following access:
     R   W     amazing-project
     R   W     blueprints-and-ideas
     R   W     gitolite-admin
     R   W     localization-efforts
     R   W     monster-crazy-project
    @R_ @W_    testing
Connection to {server.com} closed.

If you get an answer like that, it means that your key was correctly setup and you can access all the repositories listed on the response.

What keys are being used for authentication?

If you’re setting an access for an external team, they might want to share a single key and get confused on how to use it.

What you need to check it’s that when the user it’s trying to connect, the SSH connection will actually try to use the private key that matches the public key configured for access.

So, the firs step it’s to check which keys private keys are used in the SSH connection. For this, we’ll need to get the output of

ssh -v git@server.com

The debug messages should include some lines such as:

debug1: identity file /home/{your_local_username}/.ssh/identity type 1
debug1: identity file /home/{your_local_username}/.ssh/id_rsa type 1
debug1: identity file /home/{your_local_username}/.ssh/id_dsa type -1

… so you should find an identity file for each of your private keys. Ubuntu will automatically load a bunch of private keys from your user folder, but if you’re using an identity which it’s not one of these defaults, you’ll need to add using the SSH authentication agent, using

ssh-add /path/to/the/private/key

If for some reason you get a message like “Could not open a connection to your authentication agent”, you’ll need to start the authentication agent with

eval `ssh-agent`
echo $SSH_AUTH_SOCK

And then add the relevant private key.

To check with private keys are loaded on the authentication agent, use

ssh-add -l

The command will show a list of loaded identities, each with their respective fingerprint.

Now, to re-check that the configured public key matches the private key, you can get the public key fingerprint with

ssh-keygen -lf /path/to/public/key

If the fingerprint for the public it’s the same as the one from the private key, it means that you’re using the correct pair of keys.

So, that’s it?

Sadly, no, but I think these tips will help you at least diagnose the most common and silly problems before you get to dig much deeper.

If you need, you can check gitolite’s documentation on ssh troubleshooting and tips for more information.