PLGRM

what is it?

PLGRM (pronounceable like "pilgrim") is a Live Git Repository Manager. PLGRM was inspired by Gitolite, and it is very similar to Gitolite in terms of functionality (and in terms of how that functionality is implemented), but it differs in that it is intended to work with non-bare repositories whose working copies automatically update upon receiving new changesets; and in that it doesn't have nearly as many "bells and whistles."

The goal is to make it easy to manage access control on a per-repository basis, and to take care of the "magic" of creating remote repositories and configuring them to update on push.

is it any good?

Yes.

how do i use it?

PLGRM is Free/Libre Software. You are free to run, redistribute, and/or modify it under the terms of the GNU Affero General Public License, version 3 or (at your option) later.

installation

PLGRM is intended to be run as a dedicated user. So you may wish to create a new user on your server, for example:

$ sudo useradd -d /home/git -m git
$ sudo chsh -s /bin/bash git
$ sudo su git
  

Running the above commands should create a new user, update that user's shell, and (temporarily) give you shell access as that user. Note that this user's username is arbitrary and so can be something other than git.

You can get the current development version by cloning the PLGRM source repository on your server:

$ cd
$ git clone git://hz.mit.edu/plgrm.git
  

This command will create a directory called plgrm in your new user's home directory. You are welcome to rename or move this directory to an arbitrary location, but note that repositories managed by PLGRM will eventually live in a subdirectory of this location called repos.

You will also need a copy of at least one of your SSH public keys on the server, stored as username.pub, where username is an identifier for you (arbitrary except that it cannot contain periods, quotation marks, apostrophes, or spaces).

Next, run the setup script:

$ plgrm/scripts/setup_admin_repo.py
  

That should do it for the server-side setup. All other steps (creating repositories, managing access control, etc) do not require using a shell on the server.

usage

The installation process created a special repository called _admin, which you can now clone from a separate machine with the following (replace example.host.com with your server's hostname or IP address and git with a different user if necessary):

$ git clone git@example.host.com:_admin
  

The _admin repository contains public keys of all users, as well as information about repositories that should be created on the server, and about which users can access which repositories.

public key management

The keys directory should contain your public key, and other public keys can be added to it. The names of these files are important, as they will contain an identifier that PLGRM will use to determine which repositories a user can access/modify. Filenamess should have the form username.pub, or, if a single user has multiple keys, they can be named like username@something_else.pub. For example, hartz.pub, hartz@lappy-386.pub, and hartz@2.pub would be three separate keys that should all identify a user as hartz. It's perhaps also worth mentioning that these usernames are not at all related to the names of the GNU/Linux users on the server; they're identifiers only used by PLGRM.

Adding new keys to this directory and pushing to the server will automatically update the necessary bits to allow those users to connect to the server as the user you created above, using the public key(s) in that directory. However, they will not have shell access, but rather only access to Git commands (and, in particular, only to repositories managed by PLGRM).

repository management

The acl.ini file ("Access Control List") will contain information about the repositories that should be created on the server, and about which users can access which repositories. This file follows the standard syntax for .ini files, and it is initialized with the necessary structure.

The first section, groups, contains information about groups of users. Each line should look like:

groupname = user1 user2 user3 ...
  
Each group can have an arbitrary name and arbitrarily many users.

The next section, repos, describes the repositories that should be hosted on the system. Each line in this section should look like:

reponame = user1 user2 @group1 user 3 @group2 ...
  
Each line specifies permissions for a single repository (which will be created if it does not exist). The value (after the =) can contain arbitrarily many usernames or group names (prefixed with @ that should have access to that repository.

After these changes have been pushed to the server, users should be able to clone the repositories listed in the file:

$ git clone git@example.host.com:reponame

how does it work?

PLGRM uses the same approach as Gitolite for access control, gluing together functionality that already exists in OpenSSH and Git.

All repositories created by PLGRM are non-bare (i.e., they have a working copy), and they are all set up to automatically update the working copy upon receiving new changesets by setting receive.denyCurrentBranch=updateInstead in their .git/config files.

The _admin repository has an additional post-update hook that creates all new repositories specified in the acl.ini file and modifies the ~/.ssh/authorized_keys file to give all users SSH access. However, those keys' SSH access is limited. A typical entry added by PLGRM to the authorized_keys file looks like:

command="/home/git/plgrm/scripts/shell.py username",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa AAAAB3Nza...
  

The group of comma-separated values preceding each key limits that key to running a single command: the PLGRM shell.py script. Note that this script receives as an argument the PLGRM username associated with the key that was used. From there, it checks that the user was indeed running a Git command, and that the user is allowed to access the specified repository. If those checks pass, the relevant Git command is invoked.

it's broken.

E-mail Adam at hz@mit.edu.

it's missing a feature.

E-mail Adam at hz@mit.edu.