With one exception every problem I've had with Gitolite has been about the ssh connection. I've thought about how to help folks who run into the ssh nightmare. Probably the best way is to show you the actual look of the files of a working system, no one's done this yet. I've tried to do this through out the past three articles. If your curious what a file should look like, chances are, I've put a picture of the correct file up in one of the previous posts. With this post, I'm going to give you a check list that hopefully will uncover any problems you're having with your Gitolite install.
This checklist goes in the order of install. If you find your problem, you may want to re-do some of the steps further down the list to make sure everything is hooked up correctly. We'll start with, is the power plug hooked into the wall outlet...
- Have you installed Apache, Pear, and Git on the server and checked to see that they are all loaded and functional?
- Have you installed Git on your local machine and checked to see if you can create a repository?
Setting Up User Accounts on the Server
- Do you, as a regular user, have an account on the server where you want to install Gitolite?
- Do you, also, as the Gitolite Administrator, have another account on the same server, which you'll use to install Gitolite?
SSH key-pairs on the local machine
- Have you generated two key-pairs on your local machine, one to be used for your regular user login to the Gitolite server, and one to be used with Gitolite?
- Are both these key-pairs in the SSH2 1024bit RSA format?
- Are both these key-pairs named differently, example id_rsa, id_rsa.pub, and id_rsa_git, id_rsa_git.pub?
- On the key-pair you will use with Gitolite, did you not put a passphrase in the key by hitting a return when asked during the "ssh-keygen -t rsa"?
- Have you opened your public key files in an editor, and trimmed the file, to make sure there are no line feeds in the public key? It should be one long line, leave the ssh-rsa.
Putting SSH public keys on the server
- As the regular user, did you copy your public key, id_rsa.pub, to your $HOME/.ssh directory from your local machine?
- After you su into the Gitolite admin account on the server, did you copy the gitolite public key, id_rsa_git.pub, to a temp directory, not to your .ssh directory?
Setting up SSH on your local machine
- Have you placed the script to load the ssh-agent into your .bash_profile file? I have a picture of the script in a previous post.
- Have you placed a line in the ssh-agent load script in your .bash_profile to do an ssh-add for the regular user's private key?
- Have you placed another line in the ssh-agent load script in your .bash_profile to load the Gitolite administrator's private key?
- You have two ssh-add lines in the script?...just checking
- You've created a file named "config" in your .ssh directory?
- You've edited the config file so the ssh-agent knows which private key to load in the ssh-agent? See an image of what the config file looks like in a previous post.
Setting up Gitolite on the server in the Gitolite administrator's account
- Have you cloned the Gitolite software from GitHub?
- Did you change directories into the Gitolite directory, and install the Gitolite software with a ./src/gl-system-install?
- Have you checked that your env $PATH has a $HOME/bin in it by running "echo $PATH"? If not, have you inserted it, by assigning it in your .bash_profile or .bashrc file?
- Now that your path is set, from ~, have you installed the gitolite-admin bare repostory on the server by running "gl-setup ~/temp/gitadmin.pub"?
- Did you put yourself as the gitadmin in the gl-setup command by adding your gitolite administrators public key to the end of the command? Just checking again...
- Did you go to ~/repositories, and see you now have two bare repositories: gitolite-admin.git and testing.git?
Testing your SSH connection from your local machine
- Did you run "ssh gitolite-admin@gitolite_server info" and check that the output is correct? I showed the correct output in my last post.
- If you are asked for a passphrase, when you generated the gitolite_admin key-pair, did you not include a passphrase?
- If you are asked for a passprase, did the ssh-agent use the right key? Check your ssh-agent in .bash_profile for the ssh-adds, and the config file in /.ssh
- If you are seeing the shell info output, you are loading the wrong key into the ssh-agent.
- Have you checked that only one ssh-agent is running? You can kill these in windows from your task manager.
- Have you killed the running ssh-agent and started over by reopening your shell?
SSH troubleshooting on the server.
SSH is extremely permission and ownership sensitive up and down directories on both server and local machine
- If you are asked for a password, did you use, and specify, the correct public key when running gl-setup? Run it again if in doubt.
- Have you checked that the owner, both user and group, is the gitadmin user in for gitolte directories, and .ssh directories?
- Have you checked that your file permissions are correct from root down to every file in the .ssh directory. They should be 600.
- Have you made sure there are no line feeds in your public key?
- Does your /.ssh/authorized_keys file have #gitolite start and #gitolite end comments?
- Did you open your .ssh/authorized_keys file and see that you have a "command" line in your public key for every user?
- Did you check to see that these are public keys and not private keys?
- Did you compare the public key on the server with the public key on the local machine in your .ssh directory to see that they are the same?
- Did you use the Gitolite public key, and not your regular user public key, in the .ssh/authorized_keys file?
- Did you remove any other public keys in the .ssh/authorized_keys file outside of the #gitolite comment tags? If you don't, you will get the error message: "gitolite-admin does not appear to be a git repository"
- Did you remove any keys from the .ssh/authorized_keys that do not start with a "command" line?
Setting up your regular gitolite-admin repository on your local machine
- From your local home directory, did you clone the gitolite-admin repository from the server?
- Do you now have a ~/gitolite-admin directory?
- In the gitolite-admin directory do you have a conf and keydir directories?
- In your keydir directory, have you copied your two public keys for your regular account and your gitolite admin account? You should rename your regular key to something like aname.pub.
- Does your gitolite administrator public key name on the local machine match the one you used to install gitolite-admin on the server, and the one you used with the ssh-agent?
- If you have other users public keys to administer, have you renamed them, and placed them in the keydir directory?
- Have you opened your gitolite-admin/conf/gitolite.conf file and configured it for your repositories and users? I haven't covered this yet.
- Have you done an initial commit in your gitolite-admin repository?
- Have you checked your .git/config file for a remote URL entry? The Gitolite admin's remote repository URL is different than in a users URL in their .git/config.
- Have you a master branch specified in your .git/config file? I have an image of this file in my last post.
- Have you checked that your .git/config file has a section for each branch in your repository?
- Have you pushed your changes to the central repository?
After SSH Works
One after thought that I haven't dealt with yet is the ~/gitolite-admin/conf/gitolite.conf file. You'll need to give yourself permission to use the gitolite-admin repository, and every repository you want to administer, and put your public key in the ~/gitolite-admin/keydir directory. Read the documentation on using gitolite, it's pretty good.
After you pass the ssh hurdle, you can easily check that everything is working correctly by cloning the testing repository locally, changing something locally, git pulling and pushing. In your .git/config file, you should have a remote origin which tells your git pull and push where to go. Also each branch should have a section. The command to push should be "git push origin master" after a commit. One other gotcha, your user's remote URL in their local .git/config file will look something like this: "ncrow@gitolite_server:testing.git," while yours, as the gitolite adinistrator will look like, "gitolite_server:testing".
Once you get everything set up correctly, I would recommend you create a back up copy of the good key files, in case your files get hosed down the road.
Congratulations, that everything is running fine, or that you found your problem and corrected it. As I here from folks, or think of other things that could go wrong, I'll add them to this list. I would like to keep this checklist up to date, as a service to all, any suggestions on things to check are appreciated.