gitolite/conf/example.conf
Sitaram Chamarty 7124faa9f3 NAME-based restrictions
Gitolite allows you to restrict changes by file/dir name.  The syntax
for this used "PATH/" as a prefix to denote such file/dir patterns.
This has now been changed to "NAME/" because PATH is potentially
confusing.

While this is technically a backward-incompatible change, the feature
itself was hitherto undocumented, and only a few people were using it,
so I guess it's not that bad...

Also added documentation now.
2010-01-09 20:30:53 +05:30

265 lines
11 KiB
Plaintext

# example conf file for gitolite
# ----------------------------------------------------------------------------
# overall syntax:
# - everything is space-separated; no commas, semicolons, etc (except in
# the description string for gitweb)
# - comments in the normal shell-ish style; no surprises there
# - there are NO continuation lines of any kind
# - user/repo names as simple as possible; they must start with an
# alphanumeric, but after that they can also contain ".", "_", "-".
# - usernames can optionally be followed by an "@" and a domainname
# containing at least one "." (this allows you to use an email
# address as someone's username)
# - reponames can contain "/" characters (this allows you to
# put your repos in a tree-structure for convenience)
# objectives, over and above gitosis:
# - simpler syntax
# - easier gitweb/daemon control
# - specify who can push a branch/tag
# - specify who can rewind a branch/rewrite a tag
# ----------------------------------------------------------------------------
# GROUPS
# ------
# syntax:
# @groupname = [one or more names]
# groups let you club (user or group) names together for convenience
# * a group is like a #define in C except that it can *accumulate* values
# * the config file is parsed in a single-pass, so later *additions* to a
# group name cannot affect earlier *uses* of it
# The following examples should illustrate all this:
# you can have a group of people...
@staff = sitaram some_dev another-dev
# ...or a group of repos
@oss_repos = gitolite linux git perl rakudo entrans vkc
# even sliced and diced differently
@admins = sitaram admin2
# notice that sitaram is in 2 groups (staff and admins)
# if you repeat a group name in another definition line, the
# new ones get added to the old ones (they accumulate)
@staff = au.thor
# so now "@staff" expands to all 4 names
# groups can include other groups, and the included group will
# be expanded to whatever value it currently has
@interns = indy james
@staff = bob @interns
# "@staff" expands to 7 names now
@interns = han
# "@interns" now has 3 names in it, but note that this does
# not change @staff
# REPO AND BRANCH PERMISSIONS
# ---------------------------
# syntax:
# start line:
# repo [one or more repos and/or repo groups]
# followed by one or more permissions lines:
# (R|RW|RW+) [zero or more refexes] = [one or more users]
# there are 3 types of permissions: R, RW, and RW+. The "+" means permission
# to "rewind" (force push a non-fast forward to) a branch
# how permissions are matched:
# - user, repo, and access (W or +) are known. For that combination, if
# any of the refexes match the refname being updated, the push succeeds.
# If none of them match, it fails
# what's a refex? a regex to match against the ref being updated (get it?)
# BASIC PERMISSIONS (repo level only; apply to all branches/tags in repo)
# most important rule of all -- specify who can make changes
# to *this* file take effect
repo gitolite-admin
RW+ = @admins
# "@all" is a special, predefined, group name of all users
# (everyone who has a pubkey in keydir)
repo testing
RW+ = @all
# this repo is visible to staff but only sitaram can write to it
repo gitolite
R = @staff
RW+ = sitaram
# you can split up access rules for a repo as convenient
# (notice that @oss_repos contains gitolite also)
repo @oss_repos
R = @all
# set permissions to all already defined repos
# (a repository is defined if it has permission rules
# associated, empty "repo" stanza or "@group=..." line is
# not enough). *Please* do see doc/3-faq-tips-etc.mkd for
# some important notes on this feature
repo @all
RW+ = @admins
# ADVANCED PERMISSIONS USING REFEXES
# - refexes are specified in perl regex syntax
# - refexes are matched without any anchoring, which means a refex like
# "refs/tags/v[0-9]" matches anything *containing* that pattern. There
# may be text before and after it (example: refs/tags/v4-r3p7), and it
# will still match
# - if no refex appears, the rule applies to all refs in that repo
# - a refex is automatically prefixed by "refs/heads/" if it doesn't start
# with "refs/" (so tags have to be explicitly named as
# refs/tags/pattern)
# here's the example from
# Documentation/howto/update-hook-example.txt:
# refs/heads/master junio
# +refs/heads/pu junio
# refs/heads/cogito$ pasky
# refs/heads/bw/.* linus
# refs/heads/tmp/.* .*
# refs/tags/v[0-9].* junio
# and here're the equivalent gitolite refexes
repo git
RW master = junio
RW+ pu = junio
RW cogito$ = pasky
RW bw/ = linus
RW tmp/ = @all
RW refs/tags/v[0-9] = junio
# DENY/EXCLUDE RULES
# ***IMPORTANT NOTE: if you use deny rules, the order of the rules also makes
# a difference, where earlier it did not. Please review your ruleset
# carefully or test it. In particular, do not use `@all` in a deny rule -- it
# won't work as you might expect***.
# in the example above, you cannot easily say "anyone can write any tag,
# except version tags can only be written by junio". The following might look
# like it works but it doesn't:
# RW refs/tags/v[0-9] = junio
# RW refs/tags/ = junio linus pasky @others
# if you use "deny" rules, however, you can do this (a "deny" rule just uses
# "-" instead of "R" or "RW" or "RW+" in the permission field)
RW refs/tags/v[0-9] = junio
- refs/tags/v[0-9] = linus pasky @others
RW refs/tags/ = junio linus pasky @others
# Briefly, the rule is: the first matching refex that has the operation you're
# looking for (`W` or `+`), or a minus (`-`), results in success, or failure,
# respectively. A fallthrough also results in failure
# FILE/DIR NAME BASED RESTRICTIONS
# --------------------------------
# Here's a hopefully self-explanatory example. Assume the project has the
# following contents at the top level: a README, a "doc/" directory, and an
# "src/" directory.
repo foo
RW+ = lead_dev # rule 1
RW = dev1 dev2 dev3 dev4 # rule 2
RW NAME/ = lead_dev # rule 3
RW NAME/doc/ = dev1 dev2 # rule 4
RW NAME/src/ = dev1 dev2 dev3 dev4 # rule 5
# Notes
# - the "NAME/" is part of the syntax; think of it as a keyword if you like
# - file/dir NAME-based restrictions are *in addition* to normal (branch-name
# based) restrictions; they are not a *replacement* for them. This is why
# rule #2 (or something like it, maybe with a more specific branch-name) is
# needed; without it, dev1/2/3/4 cannot push any branches.
# - if a repo has *any* NAME/ rules, then NAME-based restrictions are checked
# for *all* users. This is why rule 3 is needed, even though we don't
# actually have any NAME-based restrictions on lead_dev. Notice the pattern
# on rule 3.
# - *each* file touched by the commits being pushed is checked against those
# rules. So, lead_dev can push changes to any files, dev1/2 can push
# changes to files in "doc/" and "src/" (but not the top level README), and
# dev3/4 can only push changes to files in "src/".
# GITWEB AND DAEMON STUFF
# -----------------------
# No specific syntax for gitweb and daemon access; just make the repo readable
# ("R" access) to the special users "gitweb" and "daemon"
# make "@oss_repos" (all 7 of them!) accessible via git daemon
repo @oss_repos
R = daemon
# make the two *large* repos accessible via gitweb
repo linux perl
R = gitweb
# REPO OWNER/DESCRIPTION LINE FOR GITWEB
# syntax, one of:
# reponame = "some description string in double quotes"
# reponame "owner name" = "some description string in double quotes"
# note: setting a description also gives gitweb access; you do not have to
# give gitweb access as described above if you're specifying a description
gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"
# REPO SPECIFIC GITCONFIG
# -----------------------
# (Thanks to teemu dot matilainen at iki dot fi)
# this should be specified within a "repo" stanza
# syntax:
# config sectionname.keyname = [optional value_string]
# example usage: if you placed a hook in src/hooks that requires configuration
# information that is specific to each repo, you could do this:
repo gitolite
config hooks.mailinglist = gitolite-commits@example.tld
config hooks.emailprefix = "[gitolite] "
config foo.bar = ""
config foo.baz =
# This does either a plain "git config section.key value" (for the first 3
# examples above) or "git config --unset-all section.key" (for the last
# example). Other forms (--add, the value_regex, etc) are not supported.
# SHELL ACCESS
# ------------
# It is possible to give certain users shell access as well as allow them to
# use gitolite features for their git repo access. The idea is to eliminate
# the need for 2 keys when both shell and gitolite access are needed.
# To give a user shell access, add the username to the special @SHELL group:
@SHELL = sitaram
# Do not add people to this group indiscriminately. AUDITABILITY OF ACCESS
# CONTROL CHANGES (AND OF REPO ACCESSES) WILL BE COMPROMISED IF ADMINS CAN
# FIDDLE WITH THE ACTUAL (PLAIN TEXT) LOG FILES THAT GITOLITE KEEPS, WHICH
# THEY CAN EASILY DO IF THEY HAVE A SHELL.