1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
# F=index Hosting git repositories
Gitolite allows you to setup git hosting on a central server, with
fine-grained access control and many (many!) more powerful features.
## #qi quick install
**If** you're comfortable with Unix and ssh, **and** you have a relatively
sane setup, the following steps should work:
* create a user called `git`. Login to this user.
* copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
* now run these commands:
git clone git://github.com/sitaramc/gitolite
gitolite/src/gl-system-install
gl-setup -q ~/YourName.pub
You're done. If it didn't work, well that's what the [install][] doc is for,
especially the [if you run into trouble][insttrouble] section.
**WARNING**: do **NOT** add repos or users directly on the server! You MUST
manage the server by cloning the special 'gitolite-admin' repo on your
workstation (`git clone git@server:gitolite-admin`), making changes, and
pushing them. Here's how to [add users and repos][add].
## #rtfm what to read...
Gitolite comes with a *lot* of documentation. The master TOC (see link above)
is the *only* comprehensive list of what is there, but here's an overview.
* understanding gitolite
* [what is gitolite][gl_what], and the rest of this document
* gitolite install and basic admin in [pictures][]
* gitolite and [ssh][gl_ssh]
* explaining gitolite to your *users*
* the [user][] document is all they need
* install and setup
* the "[install trouble?][insttrouble]" section, which links, among
other things, to arguably the most useful doc for a newbie: [ssh
troubleshooting][sts]!
* maybe even the complete [install][] document
* normal admin tasks done on the server
* [adding users and repos][add]
* [admin][]: add your own hooks, add existing repos into gitolite, etc.
* [rc][]: sett gitolite behaviour options (warning: some of the
variables have a security impact if you're careless)
* normal admin tasks done by changing [gitolite.conf][conf]
* basic access control
* advanced access control
* extras: personal branches, gitweb/git-daemon access, git config settings
* [gitolite.conf by example][conf_examples] may also help
* advanced use (experts only; you can shoot yourself in the foot nicely!)
* [ADCs][]: allow users to run specific shell commands (but not give them a shell)
* (also, [sample ADCs][shipped_ADCs] that come with gitolite)
* let [users create][wild] their own repos and assign permissions
* [delegate][deleg] admin rights
* [mirror][mirroring] your servers
* special installation scenarios:
* use smart-[http][] instead of ssh
* [migrate][migr] from gitosis
Finally, [tips][] has a lot of useful information.
## #gl_what what is gitolite?
Gitolite is an access control layer on top of git. Here's an "executive
summary":
* use a single unix user ("real" user) on the server
* provide access to many gitolite users
* they are not "real" users
* they do not get shell access
* control access to many git repositories
* read access controlled at the repo level
* write access controlled at the branch/tag/file/directory level,
including who can rewind, create, and delete branches/tags
* can be installed without root access, assuming git and perl are already
installed
* authentication is most commonly done using sshd, but you can also use
httpd if you prefer (this may require root access).
* several other neat features, too many to list here
## F=need_ why is gitolite needed?
Gitolite is separate from git, and needs to be installed and configured. So...
why do we bother?
Gitolite is useful in any server that is going to host multiple git
repositories, each with many developers, where some sort of access control is
required.
In theory, this can be done with plain old Unix permissions: each user is a
member of one or more groups, each group "owns" one or more repositories, and
using unix permissions (especially the setgid bit -- `chmod g+s`) you can
allow/disallow users access to repos.
But there are several disadvantages here:
* every user needs a userid and password on the server. This is usually a
killer, especially in tightly controlled environments
* adding/removing access rights involves complex `usermod -G ...` mumblings
which most admins would rather not deal with
* *viewing* (aka auditing) the current set of permissions requires running
multiple commands to list directories and their permissions/ownerships,
users and their group memberships, and then correlating all these manually
* auditing historical permissions or permission changes is pretty much
impossible without extraneous tools
* errors or omissions in setting the permissions exactly can cause problems
of either kind: false accepts or false rejects
* without going into ACLs it is not possible to give some people read-only
access while some others have read-write access to a repo (unless you make
it world-readable). Group access just doesn't have enough granularity
* it is absolutely impossible to restrict pushing by branch name or tag
name.
Gitolite does away with all this:
* it uses ssh magic to remove the need to give actual unix userids to
developers
* it uses a simple but powerful config file format to specify access rights
* access control changes are affected by modifying this file, adding or
removing user's public keys, and "compiling" the configuration
* this also makes auditing trivial -- all the data is in one place, and
changes to the configuration are also logged, so you can audit them.
* finally, the config file allows distinguishing between read-only and
read-write access, not only at the repository level, but at the branch
level within repositories.
## why did I write it?
The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and is almost the single
reason I started *thinking* about writing gitolite.
It's not just "read-only" versus "read-write". Rewinding a branch (aka "non
fast forward push") is potentially dangerous, but sometimes needed. So is
deleting a branch (which is really just an extreme form of rewind). I needed
something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
### F=morefeatures_ some more features
Here're some more features.
* simple, yet powerful, config file syntax, including specifying
gitweb/daemon access. You'll need this power if you manage lots of
users+repos+combinations of access
* apart from branch-name based restrictions, you can also restrict by
file/dir name changed (i.e., output of `git diff --name-only`)
* if your requirements are still too complex, you can split up the config
file and delegate authority over parts of it
* easy to specify gitweb owner, description and gitweb/daemon access
* easy to sync gitweb (http) authorisation with gitolite's access config
* comprehensive logging [aka: management does not think "blame" is just a
synonym for "annotate" :-)]
* "personal namespace" prefix for each dev
* migration guide and simple converter for gitosis conf file
* "exclude" (or "deny") rights at the branch/tag level
* specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking
## security
Due to the environment in which this was created and the need it fills, I
consider this a "security" program, albeit a very modest one.
The first person to find a hole that allows a non-admin user to push a change
to a repository that he is not allowed to, will get a modest reward of 5000
INR. The hole should not require enabling any of the options listed as having
a [security impact][rcsecurity] in the rc file, nor obvious things like setting
the umask too loose, etc.
## contact and license
Gitolite is released under GPL v2. See COPYING for details.
* author: sitaramc@gmail.com, sitaram@atc.tcs.com
* mailing list: gitolite@googlegroups.com
* list subscribe address : gitolite+subscribe@googlegroups.com
* IRC: #git and #gitolite on freenode. Note that I live in India (UTC+0530
time zone).
|
GitWeb