mirror of
https://github.com/wahyd4/gitolite.git
synced 2026-08-09 04:55:55 +10:00
436 lines
19 KiB
HTML
436 lines
19 KiB
HTML
<head>
|
|
<style>
|
|
body { background: #fff; margin-left: 40px; font-size: 0.9em; font-family: sans-serif; max-width: 800px; }
|
|
h1 { background: #ffb; margin-left: -30px; border-top: 5px solid #ccc; }
|
|
h2 { background: #ffb; margin-left: -20px; border-top: 3px solid #ddd; }
|
|
h3 { background: #ffb; margin-left: -10px; }
|
|
h4 { background: #ffb; }
|
|
code { font-size: 1.1em; background: #ddf; }
|
|
pre { margin-left: 2em; background: #ddf; }
|
|
pre code { font-size: 1.1em; background: #ddf; }
|
|
</style>
|
|
|
|
</head>
|
|
|
|
<p style="text-align:center">
|
|
<a href="master-toc.html">master TOC</a>
|
|
|
|
|
<a href="master-toc.html#admin">chapter TOC</a>
|
|
</p>
|
|
|
|
<!-- file: admin -->
|
|
|
|
<h1>administering and running gitolite</h1>
|
|
|
|
<p><a name="_please_read_this_first"></a></p>
|
|
|
|
<h2>please read this first</h2>
|
|
|
|
<p>Unless you know what you're doing, do not do <strong>anything</strong> manually on the
|
|
server (except when the documentation says you should, for example to add
|
|
custom hooks). In particular, adding new repositories or users or changing
|
|
the access control rules should not be done directly on the server. Things
|
|
will break. For example, if you manually create a repo on the server, it will
|
|
not have the required "update" hook, without which there is no access control
|
|
for pushes.</p>
|
|
|
|
<p>Most normal (day-to-day) gitolite admin work is done by cloning the
|
|
gitolite-admin repo from the server to your workstation, making changes to the
|
|
clone, and pushing those changes back.</p>
|
|
|
|
<p>The installation steps in the previous section include the steps to do this
|
|
clone, so you should already have one on your workstation, in
|
|
<code>~/gitolite-admin</code>. You can of course clone it anywhere else you want and use
|
|
that clone.</p>
|
|
|
|
<p>Either way, make sure you <code>cd</code> into this clone first.</p>
|
|
|
|
<p><em>Note</em>: some of the paths in this document use variable names. Just refer to
|
|
<code>~/.gitolite.rc</code> for the correct values for <em>your</em> installation.</p>
|
|
|
|
<p>Once you've cloned it, you're ready to add users and repos.</p>
|
|
|
|
<h2>adding users and repos: <a href="add.html" title="adding users and repos">Link</a></h2>
|
|
|
|
<!-- file: add -->
|
|
|
|
<h2>adding users and repos</h2>
|
|
|
|
<p>Do <strong>NOT</strong> add repos or users directly on the server! You MUST manage the
|
|
server by cloning the special 'gitolite-admin' repo on your workstation (<code>git
|
|
clone git@server:gitolite-admin</code>), making changes, and pushing them. This
|
|
section tells you how to add users and repos.</p>
|
|
|
|
<ul>
|
|
<li><p>ask each user who will get access to send you a public key. See other
|
|
sources (for example <a href="http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key">here</a>) for how to do this</p></li>
|
|
<li><p>rename each public key according to the user's name, with a <code>.pub</code>
|
|
extension, like <code>sitaram.pub</code> or <code>john-smith.pub</code>. You can also use
|
|
periods and underscores</p></li>
|
|
<li><p>copy all these <code>*.pub</code> files to <code>keydir</code> in your gitolite-admin repo
|
|
clone. You can also organise them into various subdirectories of <code>keydir</code>
|
|
if you wish, since the entire tree is searched.</p></li>
|
|
<li><p>edit the config file (<code>conf/gitolite.conf</code> in your admin repo clone). See
|
|
the <a href="conf.html" title="the access control file `gitolite.conf`">gitolite.conf</a> documentation for details on what goes in that
|
|
file, syntax, etc. Just add new repos as needed, and add new users and
|
|
give them permissions as required. The users names should be exactly the
|
|
same as their keyfile names, but without the <code>.pub</code> extension</p></li>
|
|
<li><p>when done, commit your changes and push. Any new repos you specified will
|
|
automatically be created (empty, but clonable) and users' access will be
|
|
updated as needed.</p></li>
|
|
</ul>
|
|
|
|
<!-- file: admin -->
|
|
|
|
<h2>using hooks: <a href="hooks.html" title="using hooks">Link</a></h2>
|
|
|
|
<!-- file: hooks -->
|
|
|
|
<h2>using hooks</h2>
|
|
|
|
<p><a name="customhooks"></a></p>
|
|
|
|
<h3>custom hooks</h3>
|
|
|
|
<p>You can supply your own, custom, hook scripts if you wish. Install gitolite
|
|
as usual, then:</p>
|
|
|
|
<ul>
|
|
<li>go to ~/.gitolite/hooks/common on the server and put your new hook there</li>
|
|
<li>now run "gl-setup" again</li>
|
|
</ul>
|
|
|
|
<p>You can use this procedure to install new hooks as well as to update hooks
|
|
that you had previously installed.</p>
|
|
|
|
<p><font color="red"><strong>IMPORTANT WARNINGS</strong></font></p>
|
|
|
|
<ul>
|
|
<li><p>The <code>update</code> hook in <code>hooks/common</code> is what implements all the
|
|
branch-level permissions in gitolite. If you fiddle with the hooks
|
|
directory, please make sure you do not mess with this file accidentally,
|
|
or all your fancy per-branch permissions will stop working.</p></li>
|
|
<li><p>Do not under any conditions put anything in <code>hooks/gitolite-admin</code> --
|
|
nothing in gitolite requires you to do anything here. Leave it alone!</p></li>
|
|
</ul>
|
|
|
|
<p><a name="hookchaining"></a></p>
|
|
|
|
<h3>hook chaining</h3>
|
|
|
|
<p>Sometimes you need to use git hooks for your own purposes (site-local
|
|
validations, CI integration, email notifications, or the ever popular "live
|
|
website update"!). However, the hooks you want to use may already be in use
|
|
by gitolite.</p>
|
|
|
|
<p>This section will tell you what to do in such cases. First, let's list the
|
|
hooks that gitolite uses:</p>
|
|
|
|
<ul>
|
|
<li><p>The <code>update</code> hook is used in all repos and is critical to gitolite's
|
|
access control!</p></li>
|
|
<li><p>The <code>post-receive</code> hook is used in all repos but only if mirroring has
|
|
been enabled. Shipped as <code>post-receive.mirrorpush</code>, it is renamed to
|
|
'post-receive' and installed as part of the mirroring setup.</p></li>
|
|
<li><p>The <code>post-update</code> hook is used in the <code>gitolite-admin</code> repo only, to
|
|
"compile" the configuration and so on.</p></li>
|
|
</ul>
|
|
|
|
<p>To run your own 'update' hook, just put it in a file called <code>update.secondary</code>
|
|
and install it as a hook. Gitolite's update hook will automatically chain to
|
|
it, taking care to pass it the same 3 arguments the original update hook
|
|
received from git.</p>
|
|
|
|
<p><font color="gray"></p>
|
|
|
|
<blockquote>
|
|
<p>In addition, gitolite now contains the basic infrastructure to support
|
|
multiple 'update' hooks without having to remember to chain them yourself.
|
|
See <code>hooks/common/update.secondary.sample</code> for instructions.</p>
|
|
</blockquote>
|
|
|
|
<p></font></p>
|
|
|
|
<p>For <code>post-receive</code>, (if using mirroring) do the opposite. You're normally
|
|
expected to rename the shipped 'post-receive.mirrorpush' to 'post-receive',
|
|
but don't do this. Instead, simply run <code>hooks/post-receive.mirrorpush</code> at the
|
|
end of <em>your</em> hook code. Do not worry about replicating STDIN (the documented
|
|
way in which a post-receive hook receives its input) because the mirroring
|
|
code does not use it.</p>
|
|
|
|
<p>To run your own <code>post-update</code> hook on normal repos, just install a hook called
|
|
'post-update' the usual way. It'll be installed on all normal repos but not
|
|
on the special gitolite-admin repo. If you need that for the gitolite-admin
|
|
repo, you'll have to call it <code>post-update.secondary</code>.</p>
|
|
|
|
<p>Finally, these names ('update.secondary' and 'post-update.secondary') are
|
|
merely the defaults. You can change them to anything you want; look in
|
|
conf/example.gitolite.rc for details.</p>
|
|
|
|
<p><a name="_environment_variables_available_to_hooks"></a></p>
|
|
|
|
<h3>environment variables available to hooks</h3>
|
|
|
|
<p>The following environment variables are set, and may be useful for any custom
|
|
processing you wish to do in your hook code:</p>
|
|
|
|
<ul>
|
|
<li><code>GL_USER</code> -- the user doing the push</li>
|
|
<li><code>GL_REPO</code> -- the reponame</li>
|
|
<li><code>GL_REPO_BASE_ABS</code> -- the absolute base path where all the repos are kept</li>
|
|
</ul>
|
|
|
|
<p>The following variables are also set, but are generally less useful:</p>
|
|
|
|
<ul>
|
|
<li><code>GL_BINDIR</code> -- where all the binaries live</li>
|
|
<li><code>GL_ADMINDIR</code> -- common directory for many gitolite things</li>
|
|
</ul>
|
|
|
|
<p><a name="_gl_post_init_hook"></a></p>
|
|
|
|
<h3>"gl-post-init" hook</h3>
|
|
|
|
<p>Sometimes it is necessary to do something whenever a new repo is created. If
|
|
you need this functionality, just supply a hook called "gl-post-init" with
|
|
whatever code you want in it.</p>
|
|
|
|
<p><a name="_gl_pre_git_hook"></a></p>
|
|
|
|
<h3>"gl-pre-git" hook</h3>
|
|
|
|
<p>Although git has lots of nice hooks you can tap into, they all run only on a
|
|
push. There's nothing that runs on a fetch or a clone, and there's no way to
|
|
run something <em>before</em> git-receive-pack or git-upload-pack, (as the case may
|
|
be) are invoked.</p>
|
|
|
|
<p>That's what the <code>gl-pre-git</code> hook is for. If an executable hook called
|
|
<code>gl-pre-git</code> is present, it will be invoked with the current directory set to
|
|
<code>repo.git</code>, and with a single argument which will be either <code>R</code> or <code>W</code>
|
|
depending on what the client is trying to do. The environment variables
|
|
<code>GL_USER</code> and <code>GL_REPO</code> are available. STDOUT will be forced to STDERR before
|
|
it is called, to avoid confusing the client.</p>
|
|
|
|
<p>If the code returns anything other than 0, gitolite will terminate the
|
|
operation (i.e., not run git at all), just like many git hooks do, so make
|
|
sure you end with <code>exit 0</code> or equivalent.</p>
|
|
|
|
<!-- file: admin -->
|
|
|
|
<p><a name="_other_features"></a></p>
|
|
|
|
<h2>other features</h2>
|
|
|
|
<h3>moving pre-existing repos into gitolite: <a href="moverepos.html" title="moving pre-existing repos into gitolite">Link</a></h3>
|
|
|
|
<!-- file: moverepos -->
|
|
|
|
<h3>moving pre-existing repos into gitolite</h3>
|
|
|
|
<p>It's best to split this into different use cases.</p>
|
|
|
|
<p><strong>Case 1 -- few repos</strong>: This is for moving one or two repos at a time, when
|
|
you have a copy of the repo on your workstation. It is also the <em>only</em> way if
|
|
you have push rights to the admin repo but no <em>shell</em> privileges on the
|
|
server.</p>
|
|
|
|
<ul>
|
|
<li><p>let gitolite create it as a brand new repo as described in the section on
|
|
"adding users and repos" at the top</p></li>
|
|
<li><p>cd to the clone on your workstation. Make sure all the branches are
|
|
correct and no extra stuff, "temp" branches, etc., are present</p></li>
|
|
<li><p>now run these two commands</p>
|
|
|
|
<pre><code>git push --all git@server:reponame
|
|
git push --tags git@server:reponame
|
|
</code></pre></li>
|
|
<li><p>(You could also use "git push --mirror" instead of separately doing
|
|
branches and tags, but that will carry across <em>your</em> remote refs also, and
|
|
typically you may not want that. Anyway please do a <code>git ls-remote
|
|
git@server:repo</code> to make sure all the stuff you want went through, and is
|
|
named correctly).</p></li>
|
|
</ul>
|
|
|
|
<p><strong>Case 2 -- many repos</strong>: This is when you have many existing repos to add,
|
|
and they're all bare (as good little server repos should be) and you have
|
|
shell access on the server. Here's how to do it; please note the order is
|
|
important here:</p>
|
|
|
|
<ul>
|
|
<li><p>make doubly sure they're <em>bare</em> repos ;-)</p></li>
|
|
<li><p>log on to the server and copy the repos to <code>$REPO_BASE</code> (which defaults to
|
|
<code>~/repositories</code>), making sure that the directory names end in ".git".</p></li>
|
|
<li><p>back on your workstation, add each repo (without the <code>.git</code> suffix) to
|
|
<code>conf/gitolite.conf</code> in your gitolite-admin repo clone. Give <em>some</em> user
|
|
(even a non-existent one like "DUMMY" is fine) at least "R" access to
|
|
these repos. Then add, commit, push.</p></li>
|
|
</ul>
|
|
|
|
<p><strong>Case 3 -- far too many repos</strong> (or your initials are JH ;-): This is when
|
|
you're like Case 2, except you have <em>so many</em> repos that step 3 becomes too
|
|
cumbersome (even with a script doing it for you).</p>
|
|
|
|
<p>Assuming you can group your repo names into various patterns, and can use
|
|
similar access control lines within each such group, you can use gitolite's
|
|
"wildcard repos" feature.</p>
|
|
|
|
<p>First read the <a href="wild.html" title="repositories named with wildcards">wildcard repositories</a> document, or at least skim
|
|
through it, to understand the basic concept. Then do this:</p>
|
|
|
|
<ul>
|
|
<li><p>do step 1 just like step 1 in Case 2 above</p></li>
|
|
<li><p>ditto for step 2</p></li>
|
|
<li><p>for each repo, determine who the owner should be and create files called
|
|
<code>gl-creater</code> (note spelling!) in each repo. The file should contain
|
|
exactly one line with the owner name.</p></li>
|
|
<li><p>run <code>gl-setup</code> again (you don't need to supply a pub key filename)</p></li>
|
|
<li><p>finally add the repos to the conf, maybe something like this, (in this
|
|
example, the owner name was the second component of the repo path), and
|
|
add/commit/push:</p>
|
|
|
|
<pre><code>repo pub/CREATOR/..*
|
|
C = @developers
|
|
RW+ = CREATOR
|
|
RW = WRITERS
|
|
R = READERS
|
|
</code></pre></li>
|
|
</ul>
|
|
|
|
<p><strong>Details</strong></p>
|
|
|
|
<p><font color="gray"></p>
|
|
|
|
<ul>
|
|
<li><p>why is the order of steps different in case 1 and case 2?</p>
|
|
|
|
<p>Because in case 2, the actual data is coming from an OS 'cp' (copy)
|
|
command, not via a normal push like in case 1. Since that happens outside
|
|
gitolite, it's easier to do it first, then tell gitolite about the repo so
|
|
it can add hooks. (If you tell gitolite first, it will create an empty
|
|
repo as soon as you push, then your 'cp' will have to overwrite those
|
|
files, but you'll then lose gitolite's hooks, etc. A bit more messy).</p></li>
|
|
<li><p>what's with the <code>gl-creater</code> file in case 3?</p>
|
|
|
|
<p>What the <a href="wild.html" title="repositories named with wildcards">wildcard repositories</a> document does not explain is how
|
|
ownership is <em>recorded</em> in gitolite: the <code>gl-creater</code> file contains the
|
|
owner name. If you want to "pretend" these repos were created by some
|
|
user, you need to add that in. That user then gets whatever access you
|
|
gave to "CREATOR" in the access rules (in our example, that was <code>RW+</code>).</p></li>
|
|
<li><p>why does case 3 need the <code>gl-setup</code> command?</p>
|
|
|
|
<p>An admin push only checks hooks on normal (non-wildcard) repos. It would
|
|
be too timetaking otherwise. Running <code>gl-setup</code> forces it to do this more
|
|
aggressively than an admin push, looking at wildcard repos as well as
|
|
normal ones.</p></li>
|
|
</ul>
|
|
|
|
<p></font></p>
|
|
|
|
<p>In the end, it all boils down to (a) making sure the <code>update</code> hook is correct
|
|
on all repos, wild or normal, and (b) making sure <code>gl-creater</code> contains the
|
|
owner name for wild repos. The rest of the setup is in the conf file.</p>
|
|
|
|
<!-- file: admin -->
|
|
|
|
<h3>moving the whole thing from one server to another: <a href="moveserver.html" title="moving the whole thing from one server to another">Link</a></h3>
|
|
|
|
<!-- file: moveserver -->
|
|
|
|
<h3>moving the whole thing from one server to another</h3>
|
|
|
|
<p>[<strong>NOTE</strong>: I would appreciate help testing these instructions]</p>
|
|
|
|
<p>Just copying everything won't work unless everything on the new server is
|
|
exactly the same. I suggest you don't try it unless you know what you're
|
|
doing.</p>
|
|
|
|
<p><strong>Assumptions</strong></p>
|
|
|
|
<ul>
|
|
<li>you have not changed <code>$REPO_BASE</code> on either of the servers; if you did,
|
|
substitute accordingly</li>
|
|
<li>the admin's name is "YourName" -- again, substitute accordingly!</li>
|
|
<li>the "hosting user" on both servers is "git". Substitute whatever you're
|
|
actually using (for example, if you're installing using RPM/DEB, this
|
|
would be "gitolite")</li>
|
|
</ul>
|
|
|
|
<p>There are many ways of doing this, but the most <em>generic</em> set of steps are
|
|
given below. Please follow all the steps; do not skip or improvise! Ask me
|
|
if things are not clear -- you can help me fine tune this document :-)</p>
|
|
|
|
<ul>
|
|
<li><p>(old server) <strong>disable</strong> the old server so your users will not push any
|
|
changes to it. There are several ways to do this, but the simplest is to
|
|
insert this line at the top of <code>~/.gitolite.rc</code> on the old server:</p>
|
|
|
|
<pre><code>exit 1;
|
|
</code></pre></li>
|
|
<li><p>(new server) <strong>copy</strong> the repos to the new server, <strong>except</strong> the
|
|
<code>gitolite-admin</code> repo and files called <code>gitolite-hooked</code> in the <code>hooks</code>
|
|
directory of each repo.</p>
|
|
|
|
<p>That sounds complicated but it's not. It's just:</p>
|
|
|
|
<pre><code>cd $HOME
|
|
rsync -a olduser@oldhost:repositories .
|
|
mv repositories/gitolite-admin.git $HOME/old-gitolite-admin.git
|
|
find repositories -name gitolite-hooked | xargs rm
|
|
</code></pre>
|
|
|
|
<p>Don't forget to chown repositories if git's UID changed. Gitolite expects
|
|
the hosting user to own all the files and directories it manages.</p></li>
|
|
<li><p>(workstation, new server) <strong>install</strong> gitolite normally on your new
|
|
server. Use whatever install method suits you, but you must use the
|
|
<strong>same</strong> name for the admin ("YourName" in the install instructions). You
|
|
may use a different keypair if you need to, or use the same one that
|
|
currently gets access to the old server.</p></li>
|
|
<li><p>(new server) <strong>edit</strong> the <code>~/.gitolite.rc</code> file to match the settings on
|
|
the old server, if needed. Do not copy the entire file outright -- some
|
|
of the variables (notably <code>GL_PACKAGE_CONF</code> and <code>GL_PACKAGE_HOOKS</code>) are
|
|
installation dependent and should not be touched! Do a diff or a vimdiff
|
|
and copy across only what you know <em>you</em> changed on the old server.</p></li>
|
|
<li><p>(workstation) <strong>push</strong> the config to the new server. To do this, go to
|
|
your admin clone, and:</p>
|
|
|
|
<ul>
|
|
<li><p>if you used a different keypair when installing to the new server,
|
|
copy that pubkey to this clone into <code>keydir/Yourname.pub</code>, then add
|
|
and commit the change to the pubkey</p>
|
|
|
|
<pre><code>cd gitolite-admin
|
|
cp path/to/new/YourName.pub keydir/YourName.pub
|
|
git add keydir
|
|
git commit -m "new server, new key"
|
|
</code></pre></li>
|
|
<li><p>if you did <em>not</em> use a different keypair, just make a dummy commit</p>
|
|
|
|
<pre><code>git commit -m "new server" --allow-empty
|
|
</code></pre></li>
|
|
<li><p>set the URL for the new server</p>
|
|
|
|
<pre><code>git remote --set-url origin git@newserver:gitolite-admin
|
|
</code></pre></li>
|
|
<li><p>push the config, including past history</p>
|
|
|
|
<pre><code>git push -f
|
|
</code></pre></li>
|
|
</ul></li>
|
|
</ul>
|
|
|
|
<p>And that should be that!</p>
|
|
|
|
<!-- file: admin -->
|
|
|
|
<p><a name="_custom_git_config"></a></p>
|
|
|
|
<h3>custom git config</h3>
|
|
|
|
<p>The custom hooks feature is a blunt instrument -- all repos get the hook you
|
|
specified and will run it. You can of course install hooks manually on the
|
|
server, but sometimes that's cumbersome.</p>
|
|
|
|
<p>Instead, you could set your hooks to only work if a certain "gitconfig"
|
|
variable was set. See <a href="_confother.html#rsgc" title="repo specific `git config` commands">this</a> for a way to specify "git config"
|
|
settings on a per repository basis.</p>
|