README.md



    1 ## Description
    2 
    3 TODO
    4 
    5 ## Setup
    6 
    7 ### General Git Server Setup (One time)
    8 
    9 **Note:** These steps are likely already done if you're currently hosting git
   10           repos.
   11 
   12 *   Create a service account for git repos (probably a user named "git").
   13 
   14 *   Set the git service account shell to **/usr/bin/git-shell**
   15 
   16 *   As that account, create the directory **~/git-shell-commands**
   17 
   18 *   Create the file **~/git-shell-commands/no-interactive-login**, with the
   19     following contents
   20 
   21 
   22     #!/usr/bin/env bash
   23 
   24     echo 'No soup for you!!!'
   25     exit 1
   26 
   27 
   28 ### Gitaccess setup
   29 
   30 *   Add keys for all users who will be working on any repos to the new service
   31     account's authorized_keys file
   32 
   33     *   Preceed each key with 'command="gitaccess <username>"'
   34 
   35 *   Place the gitaccess script in the service account's ~/git-shell-commands
   36     directory. These should include...
   37 
   38     *   ~/git-shell-commands/gitaccess
   39 
   40 *   Create a "users" file at the top of each bare repo (next to files like
   41     'config' and 'description')
   42 
   43     *   Place a list of usernames (from the .ssh/authorized_keys file) that are
   44         allowed write access to the repo).
   45 
   46     *   Commented lines are allowed, by starting the line with a **#**
   47         character.
   48 
   49     *   **Note:** Once all the previous steps are done per-repo, this step is
   50         the only one you'll need to manage (who has access to which repo).
   51 
   52 _- Fin -_
   53 
   54 
   55 ## Workflow
   56 
   57 If you're interested in how this works...
   58 
   59 1.  User runs 'git push <remote> <branch>', using a private ssh key for auth to
   60     the service account.
   61 
   62 2.  Server checks authorized keys file for matching public key.
   63 
   64     *   If a matching key is found, the key's specified command
   65         (command="gitaccess <username>") is executed, including the key's
   66         matching username as argument one.
   67 
   68     *   If one is _not_ found, shell exits.
   69 
   70 3.  Git pre-receive hook is executed. Username is checked (determined by
   71     previous step).
   72 
   73     *   If username is contained in the repo's users file, the push is
   74         accepted.
   75 
   76     *   If the username is _not_ in the repo's 'users' file, the push is
   77         rejected with an error message and we exit code 1.
   78 
   79 
   80 ## Components
   81 
   82 ### gitaccess
   83 
   84 The gitaccess script effectively sets up an environmental variable (GIT_USER)
   85 based on the first argument. Beyond that, it simply calls the same command git requested on git-push.
   86 
   87 
   88 ### gitaccess.pre-receive
   89 
   90 This is the pre-receive hook that is executed when any user runs 'git push
   91 <remote> <branch>'. This script parses the current repo's users file to
   92 determine if the user has push access or not. If not, it exits code 1, failing
   93 the push operation.