// Tutorial //

How To Use Gitolite to Control Access to a Git Server on an Ubuntu 12.04 VPS

Published on October 15, 2013
Default avatar
By Justin Ellingwood
Developer and author at DigitalOcean.
How To Use Gitolite to Control Access to a Git Server on an Ubuntu 12.04 VPS

Status: Deprecated

This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:

Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.

See Instead: This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.


Git is a great distributed version control system that can be used to keep track of changes and code for any kind of project. Sometimes, it is helpful to configure a git server to house your team’s projects.

Gitolite provides an access-control layer for a git server, so that you can configure user-based git access without the accompanying operating system user accounts. This provides your git contributors the privileges they need, without exposing your server to other kinds of interaction.

We will be installing these components on an Ubuntu 12.04 VPS. This tutorial assumes that you have a regular user account on this VPS with sudo privileges. Use this tutorial if you need help setting up a user account on Ubuntu.

Install Git

Log into your Ubuntu server with your regular user account.

We will be installing git from Ubuntu’s default repositories:

sudo apt-get install git-core

We now have git installed. We will want to configure a few things for git to operate properly.

Install Gitolite

Now that we have git set up correctly, we can install gitolite to manage user access to our repositories.

Gitolite is also available in Ubuntu’s default repositories. Install it with this command:

sudo apt-get install gitolite

Gitolite manages its configuration through git! To set this up properly, we’ll create a operating system user whose sole function is to interact with gitolite.

The operating system user will be called git to make it easy for our collaborators to remember. We will not set a password so that it is only accessible through using the su command.

sudo adduser --system --group --shell /bin/bash --disabled-password git

We now have a user called “git” that will handle gitolite configuration. We need to be able to access this user from a normal account. We will do this by configuring an SSH key associated with git administration.

Configure SSH Keys for Git Administration

On your local computer, which you will be using to administer git and gitolite, you need to create an SSH key pair if you have not done so already.

Note: If you already have a key pair created, you should skip this command to avoid overwriting your SSH keys.

ssh-keygen -t rsa

Accept the default location and press ENTER to configure key-based login without a password.

Copy the public key to the git server by typing:

<pre> scp ~/.ssh/id_rsa.pub <span class=“highlight”>regular_username</span>@<span class=“highlight”>git_server_IP_address</span>:/tmp/git-admin.pub </pre>

If you followed the Initial Server Setup article, you will need to allow SSH access to the git user. You can do that by editing <code>/etc/ssh/sshd_config</code> and adding git to the <code>AllowUsers</code> directive. Once you’re done, restart the SSH server:

<pre>sudo service ssh restart</pre>

Configure Gitolite

The next steps will take place back on our git server. Log back in with your normal user.

We can log in with our “git” user to initialize gitolite with the public key we just transferred.

sudo su - git

Now, we can set up gitolite with the following command:

gl-setup /tmp/git-admin.pub

Hit ENTER to pull the configuration into your editor. Scan the contents to make sure the default configuration will meet your needs. You can always change it later.

When you are finished, save and exit out of the file.

How To Administer Gitolite

Back on your local computer, you can begin administering gitolite.

If you do not already have git installed on this computer, you need to install it with:

sudo apt-get install git-core

First, we need to clone the gitolite information from our git server to our local machine:

<pre> git clone git@<span class=“highlight”>git_server_IP_address</span>:gitolite-admin </pre>

This will create a new directory called gitolite-admin within your current directory. Here, we can make changes to our access policies and then push those changes to the git server.

Add New Users to Gitolite

To add users to your projects, you will need their public keys. Gitolite works by associating the username that will be signing in with the public key with the same name. We will pretend we have a user called john for this demonstration.

On the local machine, we can change into the gitolite-admin directory and see what is inside:

cd gitolite-admin

conf    keydir

Inside, there are two directories: conf and keydir. Unsurprisingly, keydir contains user keys.

You would communicate with “john” and acquire the public key that he plans on using. You would then copy that key into this directory like this:

<pre> cp <span class=“highlight”>/path/to/john’s/public/key.pub</span> ~/gitolite-admin/keydir/john.pub </pre>

After that, you need to add the new public key to the git repository.

First, we want to configure the user name and email that will be associated with administrative git actions. Type these commands to configure this:

<pre> git config --global user.name “<span class=“highlight”>your_name_here</span>” git config --global user.email “<span class=“highlight”>your_email@address.com</span>” </pre>

You probably also want to configure git to use the editor of your choice. Type this command to specify your preferences:

<pre> git config --global core.editor <span class=“highlight”>your_editor_choice</span> </pre>

Now, we can add the new file to git:

git add keydir/john.pub

Commit the changes with a message:

<pre> git commit -a -m “<span class=“highlight”>New user John added</span>” </pre>

Push the changes up to the git server to save the results:

git push

Configure Access with Gitolite

When you added the user in the last section, you may have noticed a warning like this:

remote: 		***** WARNING *****
remote:         the following users (pubkey files in parens) do not appear in the config file:
remote: john(john.pub)

You will receive a message that the new user is not in the config file. This means that the user “john” is known to gitolite, but no access has been created for him.

We can easily add him to our configuration by editing the ~/gitolite-admin/conf/gitolite.conf file.

We will go one step further though and give him his own repository. We will create a repository called johnsproject and give him access:

nano ~/gitolite-admin/conf/gitolite.conf

repo    gitolite-admin
        RW+     =   git-admin

repo    testing
        RW+     =   @all

As you can see, the syntax is pretty simple.

We specify a git repository with the repo keyword followed by its name. Under that, we write the privilege type, an equal sign (=), and the users who should get that access.

Groups can be defined with a line like this:

<pre> @<span class=“highlight”>group_name</span> = user1 user2 user3 </pre>

After that, we can refer to a number of users like by referencing the group:

<pre> repo some_repo RW+ = @<span class=“highlight”>group_name</span> </pre>

A special group called @all references all users or all repositories, based on the context.

The permissions can be one of these values:

  • R: Read only access
  • RW: Can read or push new changes. Cannot delete refs that exist on the git server already.
  • RW+: Can push destructively, or delete refs on the server.
  • -: Has no access to the specified content.

We can give “john” full access to a new repository called johnsproject by adding these lines to the end of the file:

repo    johnsproject
        RW+     =       john

Save and close the file.

Now, we can commit this change with a new message:

<pre> git commit -a -m “<span class=“highlight”>Made John’s repo</span>” </pre>

Finally, push the changes to the git server:

git push

Now, “john” should be able to clone his project repository with the following command, from the computer where he created the public and private keys:

<pre> git clone git@<span class=“highlight”>git_server_IP_address</span>:johnsproject </pre>


You should now have gitolite configured correctly. You should be able to create git users easily without worrying about configuring accompanying operating system users and permissions every time.

If you are managing multiple projects with diverse teams, it is probably best to set up groups that correspond to projects. It might also be helpful to organize your keydir keys into subdirectories based on project. Gitolite will use them the same way, but they will be easier to find for administrative purposes.

<div class=“author”>By Justin Ellingwood</div>

Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?

You can shorten this a bit by using the configuration built in to the Ubuntu/Debian gitolite package. After doing ‘apt-get install gitolite’, skip creating the git user. Go ahead and create the ssh key and copy it to the server. Then, instead of su’ing to the git user and running gl-setup, do:

sudo dpkg-reconfigure gitolite

The reconfigure script will prompt for 1) the user Gitollite will run as (defaults to gitolite, but I normally shorten it to git); 2) the path to the directory where gitolite should be stored (defaults to /var/lib/gitolite, which I normally accept); and 3) the path to the administration public key, or the public key itself (no default. If you’ve already copied the public key to the server, give the path to it. If accessing the server from a Windows machine using Putty, you can pull up the key in puttygen on the Windows machine, and do a copy/paste of the key itself).

After that, continue from the “How to Administer Gitolite” paragraph.

If anyone is still using this, the newest version in apt is v3 and there’s a dedicated package for it so when you install, make sure to use:

sudo apt-get install gitolite3

see gitolite install docs

Hello I am getting an error when I try to clone the gitolite-admin repository.

Cloning into ‘gitolite-admin’… Received disconnect from [git server ip]: Too many authentication failures for git fatal: Could not read from remote repository.

Please make sure you have the correct access rights and the repository exists.

I set the SSHD log level to debug and I see that SSH first tries /home/git/.ssh/authorized_keys and then tries /home/git/.ssh/authorized_keys2

I followed the the SSH key creation part of this article properly and I’ve confirmed that the pub key that is in /home/git/.ssh/authorized_keys is the same one that I am using when I try connecting to the remote repo as the git user. I have also verified that the permissions on the .ssh dir are set properly (700) as are the permissions on the private key file (600) on both the local and remote machines.

I am puzzled as to why SSH is looking in the authorized_keys2 file. I am also puzzled as to why the SSH key that is in authorized_keys is not working. Has anyone else had a similar issue or know of a way to resolve this?

Just to clarify some points made earlier, if gitolite runs as the user git, then that user’s authorised keys file is different from an ordinary user’s file. It contains the administrator’s key, plus some magic to run the gitolite command when somebody makes a connection. (That’s why you don’t need to have a gitolite server running continuously - it’s run every time someone connects.) All the other user’s keys are stored as separate files in the admin project.

These are all just plain text files, so you can just look at them to get a clue what’s going on.

Thank you! This article was mighty helpful.

I have a question, this tutorial using gitolite is similar to use on a server that don’t be Digitalocean server, i need to know, so also would like to do it on others servers :)

I can connect from my machine, where i configured everything with git-admin, but i cant access from another user.

  1. I generate the public key for test machine “ssh-keygen -t rsa” he put test name and the key is test.pub.

  2. He passed me the key and i copied to gitolite-admin/keydir/test.pub

  3. git add keydir test.pub

  4. git commit -a -m ‘new user test’

  5. git push

when i tried to clone from ‘test’ machine still asking me for password.

PD: i change on etc/ssh/sshd_config AllowedUsers x y git

@noahgray: You edit the /etc/ssh/sshd_config on the remote server and add the “git” user to “AllowUsers”

Can you elaborate on editing /etc/ssh/sshd_config? Which devices is this done on? Local or remote?

Replace git@my-host with just git. Does that fix it? (Make sure you restart SSH). You have to use your linux username not your git user.name.