step by step

If the script is not cutting it for you and want to vary the technique for some reason, or you simply want to gain a better understanding of what is happening, it may be better to do each step manually instead of just using the script.

Note: all files mentioned below are assumed to be under conf/. The only place where you have to explicitly state this is in the delegation code in the appendix. The rest of the time, "conf/" is assumed.

(1) `gitolite.conf`

The main config file has these items in it. Please add them in this order.

If you follow this document completely, your gitolite.conf file can be pretty static, changing only if the master admin changes or you need to add a new host as slave to the gitolite-admin repo. Therefore you can set it up first.

Here's what it looks like:

# (1.1)---------------------------------------------------------------------
# First the main setup:

@master-admins    =   sitaram dilbert
repo gitolite-admin
    RW+ =   @master-admins
    config gitolite.mirror.master   =   "master"
    config gitolite.mirror.slaves   =   "list of slave servers"
    # you cannot use continuation lines for this; sorry!  You have to list
    # them all in ONE long line within one set of double quotes...

# (1.2)---------------------------------------------------------------------
# If you have any files with "convenience" group definitions, pull them in:

include "groups/users.conf"
include "groups/repos.conf"

# (1.3)---------------------------------------------------------------------
# Next is delegation.  If you don't want delegation, omit this section,
# and replace all "subconf" commands with "include" in the rest of this
# document.

include "host-product-map.conf"
    # create this file; see step A1 in appendix A

repo gitolite-admin
    # now that you're adding a NAME/ section, you need this for master
    # admins to retain their access
    RW+ NAME/                   =   @master-admins

include "NAME-restrictions.conf"
    # create this file; see step A2 in appendix A

# (1.4)---------------------------------------------------------------------
# Now you include the access rules for native repos
# (example: master/sam.conf)

subconf "master/HOSTNAME.conf"

# (1.5)---------------------------------------------------------------------
# After this you have the mirror config for native repos.  We place this
# *after* the access rules above, to make sure we override any mirror
# config lines accidentally added by a host admin!
# (example: mirrors/sam/p1.conf)

include "mirrors/HOSTNAME/*.conf"

# (1.6)---------------------------------------------------------------------
# Now we pull in all setup (mirror config *and* access rules) for
# non-native repos.  For the product "p1", this file will get pulled in
# when the config is processed on frodo.
# (example: slave/frodo/sam.conf)

subconf "slave/HOSTNAME/*.conf"

You'll get some warnings about missing include files; ignore them.

(2) `master/sam.conf`

For each host sam, one file called master/sam.conf is needed. This file contains just one line:

include "master/sam/*.conf"

It is pulled in by the main config file using subconf "master/HOSTNAME.conf", which -- on host sam -- translates to subconf "master/sam.conf". The only purpose of this is to setup the subconf restriction on the combined contents of master/sam/*.conf.

(3) host admins only -- `master/sam/p1.conf`

(recap: the host admins for sam can only write files in master/sam).

For each product p1 with master on host sam, the admins for host sam will create a file master/sam/p1.conf. This file will contain reponames (must start with p1/) and access rules for these repos.

If they have some common groupnames etc., they can probably put them in master/sam/users.conf or some such file and pull those in into each of their product.conf files.

By default, everything is local to their server. (Mirroring can only be setup by the master admins).

(4) `mirrors/sam/p1.conf`

For each product p1 mastered on host sam, a file called mirrors/sam/p1.conf will be created, containing mirror config lines for all repos of product p1. In this case, it could be

repo    p1/..*
        config gitolite.mirror.master   =   "sam"
        config gitolite.mirror.slaves   =   "frodo"

If this file does not exist, p1 is local to sam and not mirrored.

(5) `slave/frodo/sam.conf`

For each product that slave frodo gets from master sam, this file has the following lines

# pull in the access lines
include "master/sam/p1.conf"

# pull in the mirror config lines
include "mirrors/sam/p1.conf"

This file is pulled in on a slave server via a subconf slave/HOSTNAME/*.conf line in the main config file. On frodo, this would pull in slave/frodo/sam.conf (among others), establishing, again, a subconf restriction on @sam.

Security note: what this achieves is that the access lines, which were written by sam's admins, are parsed on frodo under the subconf restriction of "sam". This is important to prevent sam's admins from writing rules for repos they don't own and having them processed on other servers!

(6) manual sync

The new repo(s) you just created would not have been synced up to frodo. You can either make an empty commit and push, or log on to sam and run

 gl-mirror-shell request-push p1/reponame

step by step

(1) gitolite.conf

(2) master/sam.conf

(3) host admins only -- master/sam/p1.conf