master TOC | main page | single-page | license | New: Gitolite Essentials book

This is for gitolite "g3"; for older (v2.x) documentation click here

1 mirroring using gitolite

WARNING existing gitolite mirroring users please note: there are significant changes in syntax and usage compared to g2. If you're not the kind who reads documentation before doing serious system admin things, well... good luck!


Mirroring is simple: you have one "master" server and one or more "slave" servers. The slaves get updates only from the master; to the rest of the world they are at best read-only.

Gitolite extends this simple notion in the following ways:

1.1 caveats

1.2 setting up mirroring

This is in two parts: the initial setup and the rc file, followed by the conf file settings and syntax.

1.2.1 the initial setup and the rc file

On each server:

1.2.2 conf file settings and syntax

Mirroring is defined by the following options. You can have different settings for different repos, and of course some repos may not have any mirror options at all -- they are then purely local.

repo foo
    ...access rules...

    option mirror.master        =   mars
    option mirror.slaves        =   phobos deimos
    option mirror.redirectOK    =   all

The first line is easy, since a repo can have only one master.

The second is a space separated list of hosts that are all slaves. You can have several slave lists, as long as the config key starts with 'mirror.slaves' and is unique. For example.

    option mirror.slaves-1   =   phobos deimos
    option mirror.slaves-2   =   io europa
    option mirror.slaves-3   =   ganymede callisto

Do not repeat a key; then only the last line for that key will be effective.

1.3 redirected pushes

Please read carefully; there are security implications if you enable this for mirrors NOT under your control.

Normally, a master, (and only a master), pushes to a slave, and the slaves are "read-only" to the users. Gitolite allows a slave to receive pushes from a user and transparently redirect them to the master.

This simplifies things for users in complex setups, letting them use their local mirror for both fetch and push access to all repos.

Just remember that if you do this, authentication happens on the slave, but authorisation is on the master. The master is trusting the slave to authenticate the user correctly, and use the same authentication data (i.e., user alice on the slave should be guaranteed to be the same as user alice on the master).

Please note that the part of the authorisation that happens before passing control to git-receive-pack (see the access rules page) will happen on the slave as well.

The syntax for enabling this is one of these:

option mirror.redirectOK    =   all
option mirror.redirectOK    =   phobos deimos

The first syntax trusts all valid slaves to redirect user pushes, while the second one trusts only some slaves.

Note that you cannot redirect gitolite commands (like perms, etc).

1.4 manually synchronising a slave repo

You can use the gitolite mirror push command on a master to manually synchronise any of its slaves. Try it with -h to get usage info.

Tip: if you want to do this to all the slaves, try this:

for s in `gitolite git-config -r reponame mirror.slave | cut -f3`
do
    gitolite mirror push $s reponame
done

This command can also be run remotely; run ssh git@host mirror -h for details.

1.5 appendix A: HOSTNAME substitution

Wherever gitolite sees the word %HOSTNAME, it will replace it with the HOSTNAME supplied in the rc file, if one was supplied. This lets you maintain configurations for all servers in one repo, yet have them act differently on different servers, by saying something like:

subconf "%HOSTNAME/*.conf"

You can use it in other places also, for example:

RW+     VREF/NAME/subs/%HOSTNAME/       =   @%HOSTNAME-admins

(you still have to define @mars-admins, @phobos-admins, etc., but the actual VREF is now one line instead of one for each server!)

1.6 appendix B: efficiency versus paranoia

If you're paranoid enough to use mirrors, you should be paranoid enough to set this on each server, despite the possible CPU overhead:

git config --global receive.fsckObjects true

1.7 appendix C: moving the admin repo to a different master

Moving only some repos (other than the gitolite-admin repo) to a different master is easy. Just make the change in the gitolite.conf file, add, commit, and push.

Even for the gitolite-admin repo, if the current master is ok, it's the same thing; just make the change and push to the current master. Subsequent pushes will go to the new master, of course.

But if the current master is already dead, there's a bit of a catch-22. You can't push to the master because it is dead, and you can't push to any slave because they won't accept updates from anywhere but the server they think is the master.

Here's how to resolve this:

  1. On each slave:

  2. Now clone the admin repo from the new master to your workstation, change the options for the rest of the repos (if needed), then add/commit/push.

And that should be all you need to do.