Rel4tion-Wiki/maint/admin/Git_Server/Gitolite_Configuration.mdwn

Gitolite's configuration is stored in a special git repository called
'gitolite-admin.git'. Since server repositories are "bare", i.e. without a
workspace, changing the configuration is done by pulling the repository, making
changes, committing them and pushing back to the server. This is the gitolite
admin's role.

In order to access the server via SSH (needed for write access), you need to
have its address. If you already have a registered domain name already, e.g.
myproject.org, you can use that. Otherwise you can use the IP address for now.
Actually, if you installed the server on the same computer you work on, you can
simply use 'localhost' regardless of whether you have a domain name (of course
remote access requires either the IP or a domain name).

We will use an SSH address which has the form __ssh://user@host:port/path__.
Since the standard SSH port is used, we can omit it. Assuming a local server
installed on your personal computer) and assuming we called the gitolite user
__git__, the address for write access to the gitolite configuration repository
would be __ssh://git@localhost/gitolite-admin.git__.

Assume the user 'alice', who is the gitolite admin, wants to edit the
configuration as described above: pull, change, commit, push. And assume she has
a folder 'git-repos' under her home folder, where she stores her local
repositories and working trees. Then the process of editing the configuration
may begin like this:

	$ cd ~/git-repos
	$ git clone ssh://git@localhost/gitolite-admin.git
	$ cd gitolite-admin

If you use a remote server, make sure the server's firewall doesn't block SSH
traffic (or try cloning first and see if it works).

Since your SSH client doesn't know the host (i.e. the 'git' user) yet, you will
be presented with the following dialog:

	Cloning into 'gitolite-admin'...
	The authenticity of host 'localhost (::1)' can't be established.
	ECDSA key fingerprint is 91:8d:b8:6f:d2:8e:5d:64:6c:d3:a7:7c:ec:c6:88:38.
	Are you sure you want to continue connecting (yes/no)?

You have three options now:

1. Say 'no', add the key fingerprint to the list of known hosts and try again
2. Verify the key authenticity against the SSH server key, and then say 'yes'
3. Just say 'yes' and maybe verify it later

[[TODO|TODO/OPEN]] __read about SSH and explain the risks etc. of these options__ If
your server is 'localhost', i.e. your computer, then choosing 'yes' is safe.
Once the host is trusted, you will not be asked anymore to confirm each
connection.

After choosing '__yes__', the following message will appear:

	Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.
	remote: Counting objects: 6, done.
	remote: Compressing objects: 100% (4/4), done.
	remote: Total 6 (delta 0), reused 0 (delta 0)
	Receiving objects: 100% (6/6), done.

For our example user Alice, the folder tree now looks like this:

+ /
  + home
    + alice
      + git-repos
        + gitolite-admin
          + .git
            + *(repository files)*
          + conf
            + *gitolite.conf*
          + keydir
            + *admin.pub*

The *keydir* folder will contain the public SSH keys of all the people to whom
you are going to give write access to your git server. Gitolite provides
fine-grained control over who can do which changes to which repository. Right
now the only known user is the admin, and the admin's key, *admin.pub*, is
exactly the one you specified in the post-installation configuration.

The *conf* folder will contain gitolite's configuration, e.g. the access rights
of each user and each repository. Currently it contains a single configuration
file, *gitolite.conf*. It should look like this:

	repo    gitolite-admin
	        RW+     =   admin
	
	repo    testing
	        RW+     =   @all

What does it mean? At the end of the post-installation process, a setup script
named __gl-setup__ was executed automatically. That script created the
gitolite-admin repository and put the admin's publc key in the right place, but
it also created an empty repository called 'testing'. That's right, for testing.
At the moment, the admin user (alice) has full access to the gitolite-admin
repository, and all registered users (currently it's just Alice) have full
access to the testing repository.

For now this file is fine (you can keep the testing repository for now, until
you see everything works). But how do we make changes when we need to? Things we
may want to do:

- add a user
- remove a user
- add a repository
- remove a repository
- move an existing repository to gitolite
- change a user's name
- give an existing user some access rights to a repository
- remove a user's access rights to a repository
- define and use a user group (useful if several repositories have the same access configuration)

Let's see how to do them. The complete documentation for *gitolite.conf* can be
found on gitolite's website [here][conf]. You can ignore the warning at the top
of that page: Gitolite 3 exists, but Debian 7 stable uses Gitolite 2.3. However
you can get Gitolite 3 from the Debian Backports repository.

The first 6 operations are briefly described above; for information on the
others see gitolite's online documentation.

The examples in this sections assume you start with 'gitolite-admin' as the
current working directory (if you followed the commands so far, it is. Anyway
you can execute `cwd` in the terminal or look at the shell prompt, and use
`cd ~/git-repos/gitolite-admin` to move there).



# Add a user

Users are added simply by adding their public SSH keys to the gitolite-admin
repository:

1. Obtain the user's public key, and (if necessary) rename is to 'USER.pub'
   where USER is a name chosen for that user. It doesn't need to be the user's
   local username or any other particular name - it just needs to be the same
   name you use later in the 'gitolite.conf' file.
2. Put the key inside the 'keydir' folder
3. Commit the change and push to the gitolite-admin repository

For example, assume the admin Alice wants to add a user Bob, who is going to
work with her on one of her projects. Bob is known on the web by his nickname
'h4ck3r', so Alice wants to use it as the user name. Bob sends his public key
(commonly found at `~/.ssh/id_rsa.pub` on his machine) by e-mail (a telegraph is
possible too, if you wish) to Alice, and she renames it to 'h3ck3r.pub' and
copies it into the 'keydir' folder. Then she commits the change and pushes her
cloned repository to the origin (either remote or localhost, depending on where
gitolite was installed).

Assuming the initial location of the key on Alice's machine is
`~/Mail/bob_pubkey`, she can do the following:

	$ cp ~/Mail/bob_pubkey keydir/h4ck3r.pub
	$ git add keydir/h4ck3r.pub
	$ git commit
	$ git push origin master

If the user has multiple SSH keys, they can be placed in separate folders or
subfolders (the depth doesn't matter). But the files themselves need to have the
same name. For example, assume Bob has two keys: One on his laptop and one on
his PC. Then the keys may be placed in 'PC' and 'laptop' subfolders (or any
other names), i.e.:

- __keydir/laptop/h4ck3r.pub__ is Bob's public key from his laptop.
- __keydir/PC/h3ck4r.pub__ is Bob's public key from his PC.



# Remove a user

You probably want to remove the user from 'gitolite.conf'. Then remove the
user's SSH key from the gitolite-admin repository. For example, this is how
Alice removes Clair from her Gitolite server:

	$ git rm keydir/clair.pub
	$ git commit
	$ git push origin master



# Create a repository

A repository is added by adding lines to the file 'gitolite.conf'. For example,
lines like these:

	repo cool-project
	    RW+     =   alice
	    RW      =   h4ck3r

So the process would be:

	(edit the config file conf/gitolite.conf)
	$ git add conf/gitolite.conf
	$ git commit
	$ git push origin master



# Remove a repository

Removing a repository involves two steps:

1. Remove it from the config file
2. Delete it from the server

If the server is local, login as the gitolite user (in our case __git__) or as
root, and delete the repository folder. If the server is remote, use remote
access, e.g. via SSH login.



# Move an existing repository to gitolite

First, add a new repository declaration to 'conf/gitolite.conf' as in the 
"Create a repository" section above. Then push your existing repository 
to the new remote you just created, and finally check the contents of 
the remote repo to make sure everything was pushed.

	cd ~/git-repos/cool-project
	git push --all ssh://git@localhost/cool-project.git
	git push --tags ssh://git@localhost/cool-project.git
	git ls-remote ssh://git@localhost/cool-project.git



# Change a user's name

The name of the admin user is 'admin', so you may wish to change it. Or you may
wish to change a user's name for any other reason. The steps are:

1. Clone the gitolite-admin repository, if you haven't done it yet
2. Change the user's public key file user 'keydir' to the new name
3. Change all occurences of the user's name in gitolite.conf to the new name
4. Commit
5. Push

If your server is in a remote location, a mistake in the process while changing
the admin user's name may cause a situation where the admin user's access rights
have been removed by mistake and __now nobody has access to the gitolite-admin
repository__. If you want to change the admin user's name and you don't have
physical access or SSH access to the server, it's safer to create a new dummy
user and give that user full access to the 'gitolite-admin' repository, so you
can always recover to the original state in case you make a mistake.

[conf]: http://gitolite.com/gitolite/g2/conf.html



# Change a repository's name

1. Change the name of the target repository folder
2. Update the name in gitolite.conf and push the change to gitolite-admin repo
3. In the local copy of old-name.git, you probably want to change the name to
   new-name.git as well and update the *origin* remote URL