## Description

TODO

## Setup

### General Git Server Setup (One time)

**Note:** These steps are likely already done if you're currently hosting git
          repos.

*   Create a service account for git repos (probably a user named "git").

*   Set the git service account shell to **/usr/bin/git-shell**

*   As that account, create the directory **~/git-shell-commands**

*   Create the file **~/git-shell-commands/no-interactive-login**, with the
    following contents


    #!/usr/bin/env bash

    echo 'No soup for you!!!'
    exit 1


### Gitaccess setup

*   Add keys for all users who will be working on any repos to the new service
    account's authorized_keys file

    *   Preceed each key with 'command="gitaccess <username>"'

*   Place the gitaccess script in the service account's ~/git-shell-commands
    directory. These should include...

    *   ~/git-shell-commands/gitaccess

*   Create a "users" file at the top of each bare repo (next to files like
    'config' and 'description')

    *   Place a list of usernames (from the .ssh/authorized_keys file) that are
        allowed write access to the repo).

    *   Commented lines are allowed, by starting the line with a **#**
        character.

    *   **Note:** Once all the previous steps are done per-repo, this step is
        the only one you'll need to manage (who has access to which repo).

_- Fin -_


## Workflow

If you're interested in how this works...

1.  User runs 'git push <remote> <branch>', using a private ssh key for auth to
    the service account.

2.  Server checks authorized keys file for matching public key.

    *   If a matching key is found, the key's specified command
        (command="gitaccess <username>") is executed, including the key's
        matching username as argument one.

    *   If one is _not_ found, shell exits.

3.  Git pre-receive hook is executed. Username is checked (determined by
    previous step).

    *   If username is contained in the repo's users file, the push is
        accepted.

    *   If the username is _not_ in the repo's 'users' file, the push is
        rejected with an error message and we exit code 1.


## Components

### gitaccess

The gitaccess script effectively sets up an environmental variable (GIT_USER)
based on the first argument. Beyond that, it simply calls the same command git requested on git-push.


### gitaccess.pre-receive

This is the pre-receive hook that is executed when any user runs 'git push
<remote> <branch>'. This script parses the current repo's users file to
determine if the user has push access or not. If not, it exits code 1, failing
the push operation.