Mirror of the Rel4tion website/wiki source, view at <http://rel4tion.org>

[[ 🗃 ^yEzqv rel4tion-wiki ]] :: [📥 Inbox] [📤 Outbox] [🐤 Followers] [🤝 Collaborators] [🛠 Commits]

Clone

HTTPS: git clone https://vervis.peers.community/repos/yEzqv

SSH: git clone USERNAME@vervis.peers.community:yEzqv

Branches

Tags

master :: 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:

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’ 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:

Let’s see how to do them. The complete documentation for gitolite.conf can be found on gitolite’s website here. 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 kets may be placed in ‘PC’ and ‘laptop’ subfolders (or any other names), i.e.:

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 create an empty new repository as explained above, i.e. just via ‘gitolite.conf’. 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.

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
[See repo JSON]