Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 207 lines (159 sloc) 8.778 kb
817c183 @sitaramc (docfix) you need RW+ to overwrite a tag
sitaramc authored
1 # Hosting git repositories
12f75cd @sitaramc (minor doc fixes for next commit)
sitaramc authored
2
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
3 <a name="start"></a>
4
817c183 @sitaramc (docfix) you need RW+ to overwrite a tag
sitaramc authored
5 Gitolite allows you to setup git hosting on a central server, with
6 fine-grained access control and many (many!) more powerful features.
7
ddf4330 @sitaramc quick install in main README
sitaramc authored
8 ----
9
10 In this document:
11
12 * <a href="#_quick_install">quick install</a>
13 * <a href="#_what">what</a>
14 * <a href="#_why">why</a>
15 * <a href="#_main_features">main features</a>
16 * <a href="#_security">security</a>
17 * <a href="#_contact_and_license">contact and license</a>
692552d @sitaramc gitolite v2.0rc1 -- please see new developer-notes doc
sitaramc authored
18
12f75cd @sitaramc (minor doc fixes for next commit)
sitaramc authored
19 ----
e8e7bda added README and TODO
Sitaram Chamarty authored
20
ddf4330 @sitaramc quick install in main README
sitaramc authored
21 <a name="_quick_install"></a>
22
23 ### quick install
24
25 If you're comfortable with Unix and ssh, the following steps should work.
26 <font color="gray">(However, gitolite has lots and lots of useful features;
27 don't miss out on them by skipping the excellent
28 [documentation][docs]!)</font>
29
30 * create a user called `git`. Login to this user.
31 * copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
32 * now run these commands:
33
34 git clone git://github.com/sitaramc/gitolite
35 cd gitolite
36 src/gl-system-install
37 gl-setup ~/YourName.pub
38
39 You're done. Now run `git clone git@server:gitolite-admin` on your
40 workstation and [add users and repos][aur].
41
42 [aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
43
44 <a name="_what"></a>
45
46 ### what
47
48 Gitolite is an access control layer on top of git. Here's an "executive
49 summary":
50
51 * use a single unix user ("real" user) on the server
52 * provide access to many gitolite users
53 * they are not "real" users
54 * they do not get shell access
55 * control access to many git repositories
56 * read access controlled at the repo level
57 * write access controlled at the branch/tag/file/directory level,
58 including who can rewind, create, and delete branches/tags
59 * can be installed without root access, assuming git and perl are already
60 installed
61 * authentication is most commonly done using sshd, but you can also use
62 httpd if you prefer (this may require root access).
63 * several other neat features described below and elsewhere in the
64 [doc/][docs] directory.
ccd8372 aa ha! easy install script!
Sitaram Chamarty authored
65
c1bd3ca @sitaramc umpteenth doc revamp...
sitaramc authored
66 Gitolite comes with a **huge** amount of documentation. If you're absolutely
67 new, the suggested reading order is this:
68
69 * the README (this document) for a quick intro
70 * the [INSTALL][install] document
b706719 @sitaramc (here's more proof that writing code is easier...)
sitaramc authored
71 * the most common installation issues are caused by ssh. Here's how
72 [gitolite uses ssh][doc9gas]. And here's an [ssh trouble
73 shooting][doc6sts] document
c1bd3ca @sitaramc umpteenth doc revamp...
sitaramc authored
74 * the [ADMIN][admin] document
b706719 @sitaramc (here's more proof that writing code is easier...)
sitaramc authored
75 * (if you're migrating from gitosis, read [this][migr])
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
76
b706719 @sitaramc (here's more proof that writing code is easier...)
sitaramc authored
77 There is also a **[master TOC of all gitolite documentation][docs]**; use your
ddf4330 @sitaramc quick install in main README
sitaramc authored
78 browser's search function to look for likely sounding words or just browse
79 around -- you never know what you'll find!
e8e7bda added README and TODO
Sitaram Chamarty authored
80
ddf4330 @sitaramc quick install in main README
sitaramc authored
81 [Here][who]'s some information on some of the projects and
82 people using gitolite (and who, in turn, have helped shape its features).
e8e7bda added README and TODO
Sitaram Chamarty authored
83
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
84 <a name="_why"></a>
e8e7bda added README and TODO
Sitaram Chamarty authored
85
196b41e @sitaramc *major* doc revamp
sitaramc authored
86 ### why
e8e7bda added README and TODO
Sitaram Chamarty authored
87
196b41e @sitaramc *major* doc revamp
sitaramc authored
88 Gitolite is separate from git, and needs to be installed and configured. So...
89 why do we bother?
90
91 Gitolite is useful in any server that is going to host multiple git
92 repositories, each with many developers, where some sort of access control is
93 required.
94
95 In theory, this can be done with plain old Unix permissions: each user is a
96 member of one or more groups, each group "owns" one or more repositories, and
97 using unix permissions (especially the setgid bit -- `chmod g+s`) you can
98 allow/disallow users access to repos.
99
100 But there are several disadvantages here:
101
102 * every user needs a userid and password on the server. This is usually a
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
103 killer, especially in tightly controlled environments
196b41e @sitaramc *major* doc revamp
sitaramc authored
104 * adding/removing access rights involves complex `usermod -G ...` mumblings
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
105 which most admins would rather not deal with
196b41e @sitaramc *major* doc revamp
sitaramc authored
106 * *viewing* (aka auditing) the current set of permissions requires running
107 multiple commands to list directories and their permissions/ownerships,
108 users and their group memberships, and then correlating all these manually
109 * auditing historical permissions or permission changes is pretty much
110 impossible without extraneous tools
111 * errors or omissions in setting the permissions exactly can cause problems
112 of either kind: false accepts or false rejects
31cd56b @sitaramc (minor) doc tweaks
sitaramc authored
113 * without going into ACLs it is not possible to give some people read-only
114 access while some others have read-write access to a repo (unless you make
115 it world-readable). Group access just doesn't have enough granularity
196b41e @sitaramc *major* doc revamp
sitaramc authored
116 * it is absolutely impossible to restrict pushing by branch name or tag
117 name.
118
119 Gitolite does away with all this:
120
121 * it uses ssh magic to remove the need to give actual unix userids to
122 developers
123 * it uses a simple but powerful config file format to specify access rights
124 * access control changes are affected by modifying this file, adding or
125 removing user's public keys, and "compiling" the configuration
126 * this also makes auditing trivial -- all the data is in one place, and
127 changes to the configuration are also logged, so you can audit them.
128 * finally, the config file allows distinguishing between read-only and
129 read-write access, not only at the repository level, but at the branch
130 level within repositories.
131
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
132 <a name="_main_features"></a>
196b41e @sitaramc *major* doc revamp
sitaramc authored
133
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
134 ### main features
e8e7bda added README and TODO
Sitaram Chamarty authored
135
536e319 doc fixes...
Sitaram Chamarty authored
136 The most important feature I needed was **per-branch permissions**. This is
137 pretty much mandatory in a corporate environment, and is almost the single
196b41e @sitaramc *major* doc revamp
sitaramc authored
138 reason I started *thinking* about writing gitolite.
d33c408 INSTALL and README pretty much done
Sitaram Chamarty authored
139
23e4c20 README: added para about selective rewind, plus some minor fixes
Sitaram Chamarty authored
140 It's not just "read-only" versus "read-write". Rewinding a branch (aka "non
141 fast forward push") is potentially dangerous, but sometimes needed. So is
142 deleting a branch (which is really just an extreme form of rewind). I needed
143 something in between allowing anyone to do it (the default) and disabling it
144 completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
145
92d5062 doc/src: major doc/help text revamp
Sitaram Chamarty authored
146 Here're **some more features**. All of them, and more, are documented in
196b41e @sitaramc *major* doc revamp
sitaramc authored
147 detail somewhere in gitolite's [doc/][docs] subdirectory.
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
148
196b41e @sitaramc *major* doc revamp
sitaramc authored
149 * simple, yet powerful, config file syntax, including specifying
536e319 doc fixes...
Sitaram Chamarty authored
150 gitweb/daemon access. You'll need this power if you manage lots of
151 users+repos+combinations of access
261b289 mention NAME-based restrictions in README
Sitaram Chamarty authored
152 * apart from branch-name based restrictions, you can also restrict by
153 file/dir name changed (i.e., output of `git diff --name-only`)
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
154 * if your requirements are still too complex, you can split up the config
155 file and delegate authority over parts of it
196b41e @sitaramc *major* doc revamp
sitaramc authored
156 * easy to specify gitweb owner, description and gitweb/daemon access
157 * easy to sync gitweb (http) authorisation with gitolite's access config
158 * comprehensive logging [aka: management does not think "blame" is just a
159 synonym for "annotate" :-)]
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
160 * "personal namespace" prefix for each dev
161 * migration guide and simple converter for gitosis conf file
d71720d fold rebel into master :) [please read]
Sitaram Chamarty authored
162 * "exclude" (or "deny") rights at the branch/tag level
2eaa2c6 @sitaramc (minor) update changelog, features lists in both readme and doc/3
sitaramc authored
163 * specify repos using patterns (patterns may include creator's name)
164 * define powerful operations on the server side, even github-like forking
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
165
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
166 <a name="_security"></a>
196b41e @sitaramc *major* doc revamp
sitaramc authored
167
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
168 ### security
169
170 Due to the environment in which this was created and the need it fills, I
388f4d8 (IMPORTANT; read this in full) no more "wildrepos"
Sitaram Chamarty authored
171 consider this a "security" program, albeit a very modest one.
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
172
173 For the first person to find a security hole in it, defined as allowing a
174 normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
175 that the config file says he shouldn't, and caused by a bug in *code* that is
176 in the "master" branch, (not in the other branches, or the configuration file
177 or in Unix, perl, shell, etc.)... well I can't afford 1000 USD rewards like
2eaa2c6 @sitaramc (minor) update changelog, features lists in both readme and doc/3
sitaramc authored
178 djb, so you'll have to settle for 5000 INR (Indian Rupees) as a "token" prize
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
179 :-)
e8e7bda added README and TODO
Sitaram Chamarty authored
180
388f4d8 (IMPORTANT; read this in full) no more "wildrepos"
Sitaram Chamarty authored
181 However, there are a few optional features (which must be explicitly enabled
182 in the RC file) where I just haven't had the time to reason about security
183 thoroughly enough. Please read the comments in `conf/example.gitolite.rc` for
184 details, looking for the word "security".
98a4c79 (read this in full) access control for non-git commands running over ssh
Sitaram Chamarty authored
185
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
186 ----
e8e7bda added README and TODO
Sitaram Chamarty authored
187
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
188 <a name="_contact_and_license"></a>
196b41e @sitaramc *major* doc revamp
sitaramc authored
189
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
190 ### contact and license
23e4c20 README: added para about selective rewind, plus some minor fixes
Sitaram Chamarty authored
191
d78bbe8 lots of doc changes reflecting "push to admin" is default now :)
Sitaram Chamarty authored
192 Gitolite is released under GPL v2. See COPYING for details.
23e4c20 README: added para about selective rewind, plus some minor fixes
Sitaram Chamarty authored
193
5f342c0 @sitaramc more doc revamp; some notes below
sitaramc authored
194 * author: sitaramc@gmail.com, sitaram@atc.tcs.com
195 * mailing list: gitolite@googlegroups.com
196 * list subscribe address : gitolite+subscribe@googlegroups.com
197
dab35f3 @sitaramc fixup all docs to allow URLs pointing to gh-pages
sitaramc authored
198 [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
199 [install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
200 [admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
201 [migr]: http://sitaramc.github.com/gitolite/doc/migrate.html
202 [doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
203 [doc6sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
204 [who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html
5f33440 @sitaramc (minor) doc updates
sitaramc authored
205 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
b706719 @sitaramc (here's more proof that writing code is easier...)
sitaramc authored
206 [docs]: http://sitaramc.github.com/gitolite
Something went wrong with that request. Please try again.