Creating an ssh key pair

The administrator needs to first create an ssh key pair for themselves at their main workstation. In many cases, there may already be an ssh key pair, possibly generated for some other purpose. You should look in $HOME/.ssh for a pair of files called id_rsa and id_rsa.pub. If you don't find any such files, you can generate a key pair by running the ssh-keygen command.

Ideally, you will choose a strong passphrase to protect your private key when generating your ssh key pair. To use it without having to constantly type the passphrase, you will then use the ssh-agent command or any of its derivatives, such as the keychain package. However, these nuances are out of the scope of this book.

Similarly, if you had previously created a non-default key type (that is, something other than RSA for ssh protocol 2, which is the default), then it is assumed that you know what you are doing. Gitolite should work fine with DSA and ECDSA key pairs, but will probably not work with RSA protocol 1 keys.

Running the setup command

Now that you have your key pair at your workstation, you will need to get the public key (and only the public key!) over to the Gitolite hosting user's home directory on the server. One way to do this is to use the scp command, as in scp .ssh/id_rsa.pub git@host:adam.pub. You can use any other method available to you, for example rsync, or sftp, or even a USB stick. It doesn't matter how you do it as long as the file gets there and is renamed as adam.pub.

A word of warning for ssh experts: do not be tempted to automatically add this key to the Gitolite hosting user's authorized keys file using a command such as ssh-copy-id.

Once you have copied the file, you are ready to run the actual setup command, which is as follows:

gitolite setup -pk adam.pub

This command should produce an output similar to the following:

Initialized empty Git repository in /home/gitolite-test/repositories/gitolite-admin.git/ 
Initialized empty Git repository in /home/gitolite-test/repositories/testing.git/ 
WARNING: /home/gitolite-test/.ssh/authorized_keys missing; creating a new one 

You can ignore the warning about the authorized keys file being created—this is quite normal for the first time you do this. And with that, your Gitolite installation and setup are all done.

Checking over your new Gitolite server

Very few Gitolite administration tasks require logging on to the server and using the command line. Most of the day-to-day maintenance tasks (especially adding users and repositories) are done by making changes to a special repository called gitolite-admin, and pushing those changes to the server; that is, the administrator must perform the following:

You should be able to clone the gitolite-admin repository from your workstation by running git clone git@server:gitolite-admin. Git will use ssh to connect to the "git" user on the "server". By default, it will look at your $HOME/.ssh directory, find your ssh key pair, and offer the public key to the server to authenticate you. After that, things proceed pretty much as described in the earlier section on distinguishing users from each other, and Gitolite gives you access to the repository.

You should now see the usual message from a successful git clone operation, and you can enter cd gitolite-admin to see what came in:

$ cd gitolite-admin 
$ ls -a 
. .. conf .git keydir 
$ ls -a conf keydir 
conf: 
. .. gitolite.conf 

keydir: 
. .. adam.pub 

You can see where the public keys are stored. Note that Gitolite's notion of what your Gitolite username is, comes solely from the name of the public key file in the keydir directory. This is why when you copied the id_rsa.pub file from your workstation you copied it as adam.pub.

Adding a user

Although we will cover adding users in detail in a later chapter, you may want to add a beta user right away. Let's say you want to add Bob; here's how you can do this:

Adding a repository

Looking inside the conf/gitolite.conf file shows us the following:

$ cat conf/gitolite.conf 
repo gitolite-admin 
 RW+ = adam 

repo testing 
 RW+ = @all 

To add a new repository, edit this file and add a repo line similar to the ones that were added previously, followed by an access rule line, sticking to the syntax shown previously for now. Save the file, add it, commit the change, and push the commit. You should immediately see the usual response from the remote git for a successful push, but also something like the following:

remote: Initialized empty Git repository in /home/gitolite-test/repositories/t2.git/ 

This indicates that the new repository is ready for use.