Gitolite turns a config file into an ssh front door, and you push it to apply it

You administer gitolite by pushing to a repository, never by editing the server

The rule that governs everything else is stated bluntly: do NOT add new repos or users manually on the server. Users, repos, and access rules live in a special repository called gitolite-admin, and you push changes to the server to apply them. The administrative workflow starts on your workstation with:

git clone git@host:gitolite-admin

Inside that clone you will find two subdirectories, conf and keydir. Public keys go into keydir as alice.pub, bob.pub, and carol.pub for the people you are adding, and the access rules go into conf/gitolite.conf. Then the change is committed and pushed like any other repository:

git add conf
git add keydir
git commit -m "added foo, gave access to alice, bob, carol"
git push

When the push completes, gitolite adds the new users to `~/.ssh/authorized_keys` on the server and creates a new, empty, repo called foo. The consequence is that permissions are versioned and reviewable, but it is also that a mistake is a commit that takes effect immediately on push, and a removal is just as fast. There is no step between the commit and the change taking hold.

Permission lines are evaluated in order, and position is the whole meaning

The rule language is small on the surface and unforgiving in use. Here is the fuller example from the front page:

repo foo
    RW+                     =   alice
    -   master              =   bob
    -   refs/tags/v[0-9]    =   bob
    RW                      =   bob
    RW  refs/tags/v[0-9]    =   carol
    R                       =   dave

The reading given for that block is what to hold on to. alice can do anything to any branch or tag: create, push, delete, rewind or overwrite. bob can create or fast-forward push any branch whose name does not start with master, and create any tag whose name does not start with v plus a digit. carol can create tags whose names start with v plus a digit. dave can clone and fetch.

So the same repo block carries four different permission markers (RW+, -, RW and R), and the difference between bob's line and alice's line is the plus sign, which is what allows deletion and rewrites rather than only creation and fast-forward. Note what is absent: there is no write access for dave at all, only read. If a person needs to push and you gave them R, the fix is a config commit, not a server change.

A password prompt during clone means the ssh layer is wired wrong

Two warnings appear at the exact moments people get stuck. When you clone gitolite-admin or when a user clones a repo, the note reads: if you are asked for a password, something went wrong. The same warning appears for ordinary users after they have been given access. So a password prompt is not a missing key entry to work around by typing, it is a symptom, and the documented destination for it is the complete documentation rather than a retry.

The cause sits in the setup assumptions. The userid that hosts the repos must not currently have any ssh pubkey-based access, and ideally it has shell access only by su - git from some other userid on the same server, which the front page says keeps confusion to a minimum for people new to ssh. Before setup you log in as git, make sure `~/.ssh/authorized_keys` is empty or non-existent, and copy your workstation public key to $HOME/YourName.pub.

Users who need to know what they can reach run one command:

ssh git@host info

If that asks for a password too, the same diagnosis applies.

The requirement list is old, specific, and assumes a server you partly own

The server side needs any unix system, sh, git 1.6.6 or later, perl 5.8.8 or later, openssh 5.0 or later, and a dedicated userid to host the repos. The userid is called git throughout the document but the text says it can be anything, so substitute accordingly. It also has to be a brand new userid, or one you have emptied out except for `.bashrc` and similar files to make it look like one.

Those version floors are worth checking against your distribution rather than assuming. Git at 1.6.6, Perl at 5.8.8, and OpenSSH at 5.0 describe a much older server generation than a current default install provides, which is not a problem in itself but does mean you should confirm that the code paths you care about still work on the versions your distribution ships.

You also need root access, or someone to have created that userid for you and handed you a password. And there is an offline path: if your server is not connected to the internet, you clone the source using some in-between server or git bundle. The source location that clone uses is worth noting, because the canonical one is not on the code hosting site most people look at first:

git clone https://codeberg.org/sitaramc/gitolite
# (or) git clone https://github.com/sitaramc/gitolite
mkdir -p $HOME/bin
gitolite/install -to $HOME/bin

Then make yourself the administrator with `gitolite setup -pk YourName.pub`, and if that command does not run because bin is not in your PATH, either add it or run the full path instead.

Group lists add up instead of replacing, so a second definition is not a mistake

Groups exist for convenience, both for users and for repos:

@staff      =   alice bob carol
@interns    =   ashok

repo secret
    RW      =   @staff

repo foss
    RW+     =   @staff
    RW      =   @interns

The rule that trips people up is that group lists accumulate. These two lines have the same effect as the earlier definition of @staff:

@staff      =   alice bob
@staff      =   carol

So when you add a new member you append a line rather than rewriting the old one, and if you paste what looks like a complete group definition on top of an existing one you will silently widen access instead of replacing it. Group names can also nest, with @all-devs defined as @staff @interns, and @all is a special group name that is often convenient to use if you really mean all repos or all users.

The same accumulation logic cuts both ways on removal. Dropping a name from a group is the only record of the revocation, and because the change is a commit that anyone with access to gitolite-admin can push, the person who grants access and the person who takes it away share the same door.

Remote users get a handful of commands, and server shell gets many more

Users reach gitolite commands over ssh rather than a login shell, which is the point of the design. Running:

ssh git@host help

prints a list of available commands, and the most commonly used one is info, the same command that answers what repos a user has access to. All commands respond to a single argument of -h with suitable information, so a user can discover the syntax without a man page.

The asymmetry is deliberate and worth respecting. If you have shell on the server, you have a lot more commands available to you, and the front page suggests trying gitolite help. That means the administrative surface and the user surface are different, and a user restricted to ssh commands cannot reach the powerful verbs. Clone URLs follow the same shape, usually git clone git@host:reponame, with man git-clone covering the other forms.

There is no HTTP endpoint in this setup, and running gitolite over http rather than ssh is one of the topics the front page sends you elsewhere for.

The front page is a smoke test, and the real manual lives at gitolite.com

This README is described as minimal, written so you can get started with installing gitolite on a fresh userid over ssh and learning enough to do some basic access control. Everything past that is explicitly delegated to the documentation at http://gitolite.com/gitolite, which is where the concepts, background, troubleshooting, details on what is covered here, advanced features not covered here, migration from older gitolite, and running gitolite over http rather than ssh are supposed to come from. If you intend to use anything beyond basic repo creation and read or write rules, that site, not the repository front page, is your reference.

Two consequences you can see in the tree. First, there are no published GitHub releases, so the CHANGELOG file at the root is where version history lives. Second, the tree contains files that hint at migration and compatibility work, check-g2-compat and convert-gitosis-conf, along with contrib/, src/, t/, and an install script, but the front page describes none of them, so what they cover has to be confirmed before you rely on them.

One more practical note for anyone arriving through a forge: the front page tells GitHub users to click the wiki link before sending anything through github. The project's own repository at github.com/sitaramc/gitolite is a clone source, not where support happens.

Editorial conclusion

Gitolite is a good fit for an organization that already understands ssh keys and bare remotes, wants fine-grained push and tag rules, and would rather own the server than rent a forge. It is a bad fit if you need pull requests, a web interface, or HTTP access out of the box, because those live outside the minimal front page. Before you install, verify that the hosting userid has no pubkey access yet, that its authorized_keys is empty or absent, and that every person who needs access will hand you a public key rather than a password, since a password prompt during clone means the ssh layer is broken.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. Project website
4. README
5. sitaramc/gitolite on GitHub