The wildrepos feature allows you to specify access control rules using regular expression patterns, so you can have many actual repos being served by a single set of rules in the config file. The regex can also include the word
CREATOR in it, allowing you to parametrise the name of the user creating the repo.
If you're curious about the feature but you aren't sure if you want to read the whole page, here's a very simple example.
This is what the admin added to the conf file.
User 'u1' then runs
This is the effective rule list for 'foo/u1/bar' immediately after the user creates it. The parts that are not dimmed out can be changed by the creator (user 'u1') using the perms command to add 'u2' as a writer and 'u3' and 'u5' as readers:
This is the effective rule list that applies to the repo.
Note that both these "effective rule lists" were created without touching the actual conf file or any admin intervention.
And that's it for our quick intro example. The rest of this page will explain all this in much more detail.
Here's a slightly more detailed example, starting with what the admin puts in the conf file.
Note the "C" permission. This is a standalone "C", which gives the named users the right to create a repo. This is not to be confused with the "RWC" permission or its variants described elsewhere, which are about creating branches, not repos.
@prof = u1 @TAs = u2 u3 @students = u4 u5 u6 repo assignments/CREATOR/a[0-9][0-9] C = @students RW+ = CREATOR RW = WRITERS @TAs R = READERS @prof
For now, ignore the special usernames READERS and WRITERS, and just create a new repo, as user "u4" (a student):
$ git clone git@server:assignments/u4/a12 Initialized empty Git repository in /home/git/repositories/assignments/u4/a12.git/ warning: You appear to have cloned an empty repository.
Here's how the same example would look if you did not want the CREATOR's name to be part of the actual repo name.
repo assignments/a[0-9][0-9] C = @students RW+ = CREATOR RW = WRITERS @TAs R = READERS @prof
We haven't changed anything except the repo name regex. This means that the first student that creates, say,
assignments/a12 becomes the owner. Mistakes (such as claiming a12 instead of a13) need to be rectified by an admin logging on to the back end, though it's not too difficult.
You could also repace the C line like this:
C = @TAs
and have a TA create the repos in advance.
Due to projects like
+ character is now considered a valid character for an ordinary repo. Therefore, a regex like
foo/.+ does not look like a regex to gitolite. Use
foo/..* if you want that.
..* by itself is not considered a valid repo regex. Try
CREATOR/..* will also work.
A regex like
assignments/S02/A37. It will not match
But you may be surprised to find that it does not match even
assignments/S02/A37/B99. This is because internally, gitolite line-anchors the given regex; so that regex actually becomes
^assignments/S[0-9]+/A[0-9]+$ -- notice the line beginning and ending metacharacters.
Side-note: contrast with refexes
Just for interest, note that this is in contrast to the refexes for the normal "branch" permissions. Refexes are only anchored at the start; a regex like
refs/heads/masteractually can match
refs/heads/master01/baras well, even if no one will actually push such a branch! You can anchor both sides if you really care, by using
master, but that is not the default for refexes.
The words READERS and WRITERS are called "role" names. The access rules in the conf file decide what permissions these roles have, but they don't say what users are in each of these roles.
That needs to be done by the creator of the repo, using the
perms command. You can run
ssh git@host perms -h for detailed help, but in brief, that command lets you give and take away roles to users. This has some more detail.
If you want to have more than just the 2 default roles, say something like:
You can add the new names to the ROLES hash in the rc file; see comments in that file for how to do that. Be sure to run the 2 commands mentioned there after you have added the roles.
repo foo/..* C = u1 RW refs/tags/ = TESTERS - refs/tags/ = @all RW+ = WRITERS RW = INTERNS R = READERS RW+D = MANAGERS
Please make sure that none of the role names conflict with any of the user names or group names in the system. For example, if you have a user called "foo" or a group called "@foo", make sure you do not include "foo" as a valid role in the ROLES hash.
You can keep things sane by using UPPERCASE names for roles, while keeping all your user and group names lowercase; then you don't have to worry about this problem.
You can setup some default role assignments as soon as a new wild repo is created.
Enable the 'set-default-roles' feature in the rc file by uncommenting it if it is already present or adding it to the ENABLE list if it is not.
Supply a set of default role assignments for a wild repo regex by adding lines like this to the repo config para:
option default.roles-1 = READERS @all option default.roles-2 = WRITERS @senior-devs
This will then behave as if the perms command was used immediately after the repo was created to add those two role assignments.
If you want to simulate the old (pre v3.5)
DEFAULT_ROLE_PERMS rc file variable, just add them under a
repo @all line. (Remember that this only affects newly created wild repos, despite the '@all' name).
See the section on
OWNER_ROLENAME in the rc file page.
In order to see what repositories were created from a wildcard, use the 'info' command. Try
ssh git@host info -h to get help on the info command.
Run the whimsically named "D" command -- try
ssh git@host D -h for more info on how to delete a wild repo. (Yes the command is "D"; it's meant to be a counterpart to the "C" permission that allowed you to create the repo in the first place). Of course this only works if your admin has enabled the command (gitolite ships with the command disabled for remote use).
A wild repo is created by one specific user. This user is usually called the creator of the repo: his username is placed in a file called gl-creator in the (bare) repo directory, any permissions given in the gitolite.conf file to "CREATOR" will be applicable to this user, he is the only person who can give permissions to other users (by running the 'perms' command), etc.
But, as I said in this mail:
Until about a year ago, Gitolite only knew the concept of a "creator", and there was only one. But then people started seeing the need for more than one "owner", because wild repos may be *created* by one person, but they often needed to be *administered* by one of several people. So now, even though large parts of the documentation probably conflate "creator" and "owner", you can see wild.html ([wild]) and rc.html ([rc]) to actually understand how this larger group become the "owner".