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 *   In each repo you want to controll access to, place the following in
   36     <repo>/hooks/pre-receive...
   37 
   38     source ~/git-shell-commands/gitaccess.pre-receive
   39 
   40 *   Place git access files in the service account's ~/bin directory (create if
   41     necessary). These should include...
   42 
   43     *   ~/git-shell-commands/gitaccess
   44 
   45     *   ~/git-shell-commands/gitaccess.pre-receive
   46 
   47 *   Create a "users" file at the top of each bare repo (next to files like
   48     'config' and 'description')
   49 
   50     *   Place a list of usernames (from the .ssh/authorized_keys file) that are
   51         allowed write access to the repo).
   52 
   53     *   Commented lines are allowed, by starting the line with a **#**
   54         character.
   55 
   56     *   **Note:** Once all the previous steps are done per-repo, this step is
   57         the only one you'll need to manage (who has access to which repo).
   58 
   59 _- Fin -_
   60 
   61 
   62 ## Workflow
   63 
   64 If you're interested in how this works...
   65 
   66 1.  User runs 'git push <remote> <branch>', using a private ssh key for auth to
   67     the service account.
   68 
   69 2.  Server checks authorized keys file for matching public key.
   70 
   71     *   If a matching key is found, the key's specified command
   72         (command="gitaccess <username>") is executed, including the key's
   73         matching username as argument one.
   74 
   75     *   If one is _not_ found, shell exits.
   76 
   77 3.  Git pre-receive hook is executed. Username is checked (determined by
   78     previous step).
   79 
   80     *   If username is contained in the repo's users file, the push is
   81         accepted.
   82 
   83     *   If the username is _not_ in the repo's 'users' file, the push is
   84         rejected with an error message and we exit code 1.
   85 
   86 
   87 ## Components
   88 
   89 ### gitaccess
   90 
   91 The gitaccess script effectively sets up an environmental variable (GIT_USER)
   92 based on the first argument. Beyond that, it simply calls the same command git requested on git-push.
   93 
   94 
   95 ### gitaccess.pre-receive
   96 
   97 This is the pre-receive hook that is executed when any user runs 'git push
   98 <remote> <branch>'. This script parses the current repo's users file to
   99 determine if the user has push access or not. If not, it exits code 1, failing
  100 the push operation.