gitolite administration

Gitolite administration is fairly simple.  Gitolite uses Git itself to manage the git repositories.  As a result many of the administrative tasks are wrapped around Git commands.  The gitolite-admin repository is used to store the project members and repository information. Inside this repository we have two folders, “conf” and “keydir“.

The conf folder contains a file gitolite.conf.  this file is used to maintain the repositories traced by gitolite, and the users who are allowed to access these git repositories.
[sourcecode language=”bash”]
@admins = root administrator
@devs = dev1 dev2
@qa = qa1 qa2
repo gitolite-admin
RW+ = @admins
repo testing
RW+ = @all
repo src/project1
RW+ = @devs
R = @qa
repo qa
RW+ = @qa
[/sourcecode]
The repositories are stored in the folder configured at installation.  The path to the repository in gitolite.conf is the relative path from that folder.  If you installed gitolite with the default values then this folder is located in the home folder of the Git user setup and configured during install in a sub-folder repositories.

Git repositories

In the repositories folder you will find the git repositories as you would expect to see them.  These are all bare repos, and you don’t really need to touch them.

From the sample configuration provided above, you would expect to see the following folder structure in the gitolite repositories folder

Adding new repositories

Edit the gitolite.conf file to add a new project.
[sourcecode language=”bash”]
@admins = root administrator
@devs = dev1 dev2
@qa = qa1 qa2
repo gitolite-admin
RW+ = @admins
repo testing
RW+ = @all
repo src/project1
RW+ = @devs
R = @qa
repo qa
RW+ = @qa
[/sourcecode]

To add a new project to gitolite, add the following text to the conf file to create a new project called project2 in the src folder located in the repositories location.
[sourcecode language=”bash”]
repo src/project2
    RW+ = @devs
    R = @qa
[/sourcecode]

After adding the project to the config file, you will need to commit the results.  Once you have pushed these commits to the server, gitolite will create a new bare repository at the specified location.
[sourcecode language=”bash”]

git commit -a -m"initialized project2"
git push origin
[/sourcecode]
The first command commits the changes to the gitolite-admin repository that you cloned to your workstation.  The next step publishes those changes to the server which instructs gitolite to configure the repositories with the updated access rights, and to create any new repositories that have been added.  Any new repositories created will be placed inside the configured repositories location or off the repositories folder placed in the Git users home folder on the server.  You users should not access these repos directly.  Now all your users can access their projects by cloning them from gitolite using the git clone command.
[sourcecode language=”bash”]
git clone git@server:src/project2
[/sourcecode]

Now you have cloned the new repository to your local machine.  Now you can add files and get started on the new project.  Remember to add and commit your changes before pushing those changes to the server.

Deleting repositories

To delete a project tracked by gitolite, you need to do two steps.  Take extreme care when removing projects.  Get it wrong and you could lose your entire project history.  I recommend that you backup the git server before performing any of these tasks.

Edit the gitolite.conf file to remove a project.  In this sample, we remove project1 from the gitolite.conf file.
[sourcecode language=”bash” highlight=”8,9,10″]
@admins = root administrator
@devs = dev1 dev2
@qa = qa1 qa2
repo gitolite-admin
RW+ = @admins
repo testing
RW+ = @all
repo src/project1
    RW+ = @devs
    R = @qa
repo qa
    RW+ = @qa
repo src/project2
    RW+ = @devs
    R = @qa
[/sourcecode]

Once this file is pushed to the server, gitolite will stop tracking the project.  the bare git repository still exists in the gitolite repository folder, but no one will have access rights to that project.  To completely delete the project, login as the git user and navigate down to the location where the project1 repository is located and delete it.  If your server is on the Mac or a [U|L]inx box, then you can delete the repository with the following commands

[sourcecode language=”bash”]

cd repositories/src
rm -rf project1.git
[/sourcecode]

that’s it.  It’s really pretty easy.   there are methods to do this automatically, but I think that could be dangerous, but it might be something to explore later.

importing existing projects

Importing an existing git repository is very easy.  All you need to do is change or add a remote location to the repository configuration and push to that server.

To add a remote to your existing project do the following.
if your gitolite project is empty do this:

[sourcecode language=”bash”]

git remote add <name> git@server:<project>
git push
[/sourcecode]

or if you are connecting to an existing gitolite project that has a other data, do this instead
[sourcecode language=”bash”]

git remote add <name> git@server:<project>
git pull <name>
[/sourcecode]
merge any conflicts and commit the results.
[sourcecode language=”bash”]
git push all
[/sourcecode]
this will push the committed results to all remotes. If this is not what you want, then just push to the new remote.

Once you have pushed your existing project into gitolite, you might want to swap the git origin to point to the new project location.  This is how you do that.
[sourcecode language=”bash”]

git remote rm origin
git remote add origin git@server:<project>
git remote rm <name>
[/sourcecode]
Now you have your existing git project imported into gitolite.  There are ways to import projects from other source control systems.  Git can import directly from CVS and SVN.  Scripts could easily be written to support other systems as needed.

Repository access rights

Repository access rights are controlled through the assignment of a string that represents the desired access level to the project.  The string is formatted like a regular expression string.  For the purposes of this article, we are not going to do that but refer you instead to the gitolite documents.
[sourcecode language=”bash”]
repo src/project2
&nbsp;&nbsp;&nbsp;&nbsp;RW+ = @devs
&nbsp;&nbsp;&nbsp;&nbsp;R = @qa
[/sourcecode]

The lines below the repo declaration designate the access rights for each user, or groups of users.  There are no limits to the number of rules you can assign to each repo.  That is really up to your and your development requirements.  The most common permissions are:

  • R, for read only
  • RW, for push existing ref or create new ref
  • RW+, for “push -f” or ref deletion allowed (i.e., destroy information)
  • - (the minus sign), to deny access

As you can see, it is pretty easy to manipulate the access rights to a project tracked under Gitolite.  So far in my limited time using gitolite, I have not had the need to use any complex access rights methods, but I can see that happening as we move forward with our product development.

Users

Adding and deleting users is as easy as copying or deleting their security credentials from the keydir, and editing the gitolite.conf file to remove the user.  The security credentials used by gitolite is a standard OpenSSL public certificate that you can generate using the tools provided with Git.  This article assumes that you are developing software on the Mac and have installed Git using Macports.  OpenSSL is a sub component of Git, so the port install command will automatically install OpenSSL.

If you are on Windows you have a couple of options.  The standard Git Bash shell that is installed using the Git installer provides the OpenSSL tools you need to create your public certificate.

Once you have gathered the key or keys for the new users, place the public certificates into the gitolite-admin/keydir folder that was created when you cloned the gitolite-admin repository.  give each of the users a unique user name and then name the users public certificate <user>.pub where <user> is the unique name chosen for that user.  This name will be used by gitolite to assign project permissions the user, nothing more.

Once the public certificate is placed in the keydir folder, you just need to add that new file to the gitolite-admin repository using standard git commands.
[sourcecode language=”bash”]

git add dev3.pub
git commit -a -m"added dev3"
git push origin
[/sourcecode]

Now you need to configure user “dev3” access rights to a project.
[sourcecode language=”bash” highlight=”2,10″]
@admins = root administrator
@devs = dev1 dev2 dev3
@qa = qa1 qa2
repo gitolite-admin
RW+ = @admins
repo testing
RW+ = @all
repo qa
RW+ = @qa
R- = dev3
repo src/project2
RW+ = @devs
R = @qa
[/sourcecode]

With the edits highlighted here, we have added the user “dev3” to the devs group and denied that user access to the qa project.  Save the changes to the gitolite.conf file and then commit and push the changes to the server.

It is that easy.

Deleting is obvious, just remove the user from the conf file at a minimum.  This disables that user from accessing the projects.  You can take that a step further and either create a denied users group, or just delete the pub file from the keydir folder and commit and push the results to the server.

Administering Git repositories using gitolite is really fairly easy if you understand the Git paradigm.  Having managed bare repositories before, gitolite simplified the configuration and maintenance of a source control system while using Git as the core technology.  I hope you will find this tool as useful as I have.

Up Next:  Configuring Gitolite hooks