Home‎ > ‎

gitolite-tutorial

gitolite tutorial

April 17, 2012: The gitolite author and the author of this site decided that it is best to make these changes: step 5 changed to reflect new gitolite.




My name is Sena Wario and this is my gitolite tutorial.  Gitolite sets up a central "server" to host many git repositories for many users.

I initially wrote this because someone on #git said "people always assume the official documentation is crap; that's why they look for tutorials".  But a better reason is that gitolite comes with an enormous amount of documentation, (just the master TOC/index has more than 300 entries!) so the sheer size can be overwhelming for a rank newbie.  Also, a lot of people start using gitolite before they have acquired enough knowledge of git, which makes things worse.

My tutorial uses words and phrases borrowed from the official gitolite documentation, so don't be surprised if it sounds similar in places!

Also, since everyone's environment will not be exactly the same, you can expect some errors while following this on your machine. Let me know about them (senawario@gmail.com) so I can add tips if needed.

Anything you have to type is in bold. System responses (when shown) are in normal font.


For this tutorial I will be using Fedora 15, but it should work with any Linux.  Probably any Unix even.  (The only non-portable command in this whole tutorial is the "useradd" command; see below for details.  The rest should work fine anywhere).

As the gitolite documentation says, gitolite is invoked by ssh, so actually any "unix user" on the server can become a "gitolite server".  In this tutorial we will create a user called "gitolite" to host our gitolite server.  (This means developers will access repos with URLs that look like gitolite@server.name:repo (or maybe ssh://gitolite@server.name:port-number/repo if you need to use a port number other than 22).

According to the official install document, gitolite has 3 different methods of installation -- "package", "root", and "non-root".  The "non-root" method, is the least intrusive of these (you just have to create one userid and everything else happens within that userid, without touching the rest of the system), so this is what this tutorial is about.  [Note: a fourth method, "from-client", exists but is now deprecated].


Step 1: SET UP/CHECK PREREQUISITES


Server IP/name and OS: You will need some flavour of Unix for the server.  I've only tested with Fedora 16, though.

In this tutorial we will pretend the server is called glh (stands for "gitolite host").

Server Software: You will need a POSIX compatible shell, perl, and git (at least version 1.6.6). I believe that installing git using your package manager will get you the others also so just do that!

Server Accounts: You will need an account on the server for which you have the password. This account will become the "gitolite hosting user". In this tutorial we will create a new user called gitolite and use that as the hosting user. (The following commands work on Fedora; your distro/OS may be different.  For instance, I am told Debian uses "adduser" instead of "useradd").

# useradd gitolite    # please find and use equivalent command for your distro
# passwd gitolite
Changing password for user gitolite.
New password: 
Retype new password: 
passwd: all authentication tokens updated successfully.

Server Account Environment: $HOME/bin should be part of the default $PATH for this user.  If it isn't, fiddle with the .bashrc or .bash_profile or similar files and add it somehow.

Administrator: You :-)

Administrator's Workstation OS: Shouldn't really matter...

Administrator's Workstation Software: You only need git and some ssh client.  If you're using Windows, msysgit is the best.  YMMV.  (This tutorial is not about getting ssh to work so please do not ask me for help on that.  The gitolite documentation has lots of info on ssh).


Step 2: MAKING YOUR PUBKEY


On your workstation, run the following command

$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/sena/.ssh/id_rsa): 
Created directory '/home/sena/.ssh'.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/sena/.ssh/id_rsa.
Your public key has been saved in /home/sena/.ssh/id_rsa.pub.
The key fingerprint is:
a9:fc:07:e8:d2:20:36:22:f8:00:c2:17:ea:5c:3b:a8 sena@sita-lt.atc.tcs.com
The key's randomart image is:
    (some unimportant output deleted)

You don't have to create a new key. If you already have a keypair, it will ask you if you want to overwrite it, like this:

$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/sena/.ssh/id_rsa):
/home/sena/.ssh/id_rsa already exists.
Overwrite (y/n)?

Just say "n" and use your existing keypair for the next step.

If you're on Windows under "msysgit"'s bash shell, the commands are pretty much the same. The location of the files will be different, but the command will print very clearly where the two files (private key: id_rsa, and public key: id_rsa.pub) are placed. Adjust accordingly.


Step 3: COPYING YOUR PUBKEY TO THE SERVER


We need to copy your pubkey (~/.ssh/id_rsa.pub) from your workstation to the userid gitolite on the server glh. Do this on your workstation ("sena" is my first name, in case you forgot; please use your own here!):

$ scp ~/.ssh/id_rsa.pub gitolite@glh:sena.pub
The authenticity of host 'glh (<IP address deleted for tutorial>)' can't be established.
RSA key fingerprint is d2:5e:91:01:d8:74:a4:43:f0:3d:0a:21:b2:0f:92:1c.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'glh' (RSA) to the list of known hosts.
gitolite@glh's password:
id_rsa.pub                              100%  406     0.4KB/s   00:00

Step 4: GETTING THE GITOLITE SOFTWARE TO YOUR SERVER


The rest of the installation is done from the server, so log on to the server as gitolite, somehow.  For example, you could log on as some other user and then "su - gitolite".

Note: Ssh-ing in directly may not work after the initial install succeeds, because your pubkey now gets sent, and on the other side, gitolite kicks in instead of giving you a shell.  If that happens, you will need to force password authentication to get a shell: try ssh -o preferredauthentications=password gitolite@glh

Once you've logged in to the gitolite user on server glh you must download the gitolite software.  If your server has direct internet connectivity, this is pretty easy:

$ git clone git://github.com/sitaramc/gitolite.git

If your server does not have direct internet connectivity, find some machine that does, and use it as an intermediary, like this:

# on an internet connected workstation:
$ git clone git://github.com/sitaramc/gitolite.git
$ cd gitolite
$ git bundle create /tmp/gitolite.bdl --all

# now find some way of getting that file /tmp/gitolite.bdl from /tmp on
# the internet connected workstation, to /tmp on the "glh" server

# once that is done, do this:
$ git clone /tmp/gitolite.bdl gitolite

Step 5: THE ACTUAL INSTALL


On the server still, as user "gitolite", do this:

$ mkdir bin
$ gitolite/install -ln
$ gitolite setup -pk sena.pub
Initialized empty Git repository in /home/gitolite/repositories/gitolite-admin.git/
Initialized empty Git repository in /home/gitolite/repositories/testing.git/
WARNING: /home/gitolite/.ssh/authorized_keys missing; creating a new one

Step 6: CLONING THE ADMIN REPO TO THE WORKSTATION


Now you have to get back to your workstation, and do this:

$ git clone gitolite@glh:gitolite-admin
Cloning into gitolite-admin...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 6 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (6/6), done.

This means you have successfully installed gitolite and you are now ready to start using it.

However, if this does not work, or if it works only if you use "git clone gitolite@glh:repositories/gitolite-admin" (note the extra "repositories/") or something like that, then your ssh setup is not working.  See the main gitolite project documents for an ssh-troubleshooting guide, or online here.


Step 7: ADDING NEW USERS AND REPOS


First, obtain pubkeys for your users. We will start with the example users 'alice" and "bob".

Ask both of them to generate a keypair just as you did in "step 2" of your tutorial, and send you their keys somehow. Save them with their respective names (alice.pub and bob.pub) in /tmp of your workstation.

Now you have your two users, let us assume that your two new repos are "foo" and "bar". The "foo" repo must be writable by alice, but read-only to bob. The "bar" repo is the other way around -- writable by bob, read-only to alice.

Now, on your workstation, do this:

$ cd gitolite-admin
$ cp /tmp/alice.pub keydir
$ cp /tmp/bob.pub keydir
$ vim conf/gitolite.conf

Of course, instead of vim you can use whatever editor you like. Anyway, when the editor pops up, you will see lines like this:

repo    gitolite-admin
        RW+     =   sena

repo    testing
        RW+     =   @all

Now add these lines:

repo    foo
        RW      =   alice
        R       =   bob

repo    bar
        RW      =   bob
        R       =   alice

Save the file and quit.

Now type in the following commands.  Note: If the commit command fails with an error saying *** Please tell me who you are., you should read what it says, run the commands it suggests, and retry the commit command.

$ git add keydir conf
$ git commit -m 'added users alice and bob, repos foo and bar' [master 6a18c9c] added users alice and bob, repos foo and bar 1 files changed, 9 insertions(+), 0 deletions(-) $ git push origin master Counting objects: 7, done. Delta compression using up to 2 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (4/4), 364 bytes, done. Total 4 (delta 1), reused 0 (delta 0) remote: Already on 'master' remote: creating bar... remote: Initialized empty Git repository in /home/gitolite/repositories/bar.git/ remote: creating foo... remote: Initialized empty Git repository in /home/gitolite/repositories/foo.git/ To gitolite@glh:gitolite-admin a02297b..6a18c9c master -> master

And you're done!

Comments