FluidMotion » NaibsPages » News » Gitosis: HOWTO

Gitosis: HOWTO

15 November 2009 20:09


So you have been using git and you are liking its ease of day to day use as well as other aspects of git that make it wonderful (each clone is a complete copy of the entire history ...) So you want to create your own repository or two, and possibly invite others to contribute to your repository. How to easily manage it ? This is where gitosis comes in. It provides you with an easy means to manage access to repositories all via a text file. All access is controlled via SSH keys (ie no need to create local users on the hosting server)

Setting up Gitosis

There are two types of gitosis packages in the gentoo tree

  • gitosis
  • gitosis-gentoo

gitosis-gentoo is a fork of gitosis with modifications for Gentoo Overlays as well as being actively worked on. There is no difference in setting up gitosis or gitosis-gentoo so the actual choice is down to you to what you use.

emerge gitosis # or gitosis-gentoo
emerge sudo # this is needed for setting up the gitosis environement

If you do not have an ssh key you will need to generate one now

$ ssh-keygen -t rsa

This will create ~/.ssh/id_rsa (your private key) and a ~/.ssh/id_rsa.pub (the public key). The *.pub file is what will be used to initialize gitosis

$ sudo -H -u git gitosis-init < ~/.ssh/id_rsa.pub  # or whatever ssh *.pub file you plan to use to setup gitosis
Initialized empty Git repository in /var/spool/gitosis/repositories/gitosis-admin.git/
Reinitialized existing Git repository in /var/spool/gitosis/repositories/gitosis-admin.git/ 

This is done so gitosis-init is run by user "git", from its home directory (/var/spool/gitosis by default on gentoo) Now this has seeded the gitosis working directory. Time to git clone the gitosis-admin.git repo to allow modifications

$ git clone git@YOUR_SERVER:gitosis-admin.git
remote: Counting objects: 5, done. remote:
Compressing objects: 100% (4/4), done.
remote: Total 5 (delta 0), reused 5 (delta 0)
Receiving objects: 100% (5/5), done.

Congratulations you now have gitosis all setup and functional. It is now ready to modify to add new repositories and users There should now be a gitosis-admin folder. Within this folder is 1) gitosis.conf This is the main configuration file for gitosis 2) keydir/ This directory contains all the ssh keys used for user-management. You will notice one key is present, the one you used to initialize gitosis. Gitosis would have taken the data from the end of the ssh key (USERNAME@HOSTNAME) to name this admin ssh public key. For now we assume this file is called admin@localhost.pub



  • emerge the required gitosis package (vanilla or gitosis-gentoo
  • generate ssh key
  • initialise gitosis using "sudo"
  • clone the gitosis-admin repo



    Creating your first repository

    The creation of a new repository is a 2 part process. The 1st is referencing it within gitosis.conf. The 2nd is to create a git repo locally and reference the remote origin before a push. The gitosis.conf file should look something like this

    [group gitosis-admin] 
    writable = gitosis-admin 
    members = admin@localhost

    Repositories are all controlled via these [group $GROUP_NAME] blocks. Here we see there is:

    • group created called "gitosis-admin"
    • a writable repository called "gitosis-admin"
    • member identified as "admin@localhost" (name taken from the filename of the ssh key in keydir/)

    To create a new repository we either add its name to the writables list in the gitosis-admin group, or make a new group. For now we will add it to the gitosis-admin group - additional groups will be covered in user management.

    [group gitosis-admin]
    writable = gitosis-admin test_repo 
    members = admin@localhost 


    Once this change to gitosis.conf is pushed back to origin it will inform gitosis that there is a repository called test_repo

    $ git status  # On branch master # Changed but not updated:
    # (use "git add <file>..."; to update what will be committed)
    # (use "git checkout -- <file>..."; to discard changes in working directory) #
    # modified:   gitosis.conf # no changes added to commit (use "git add"; and/or "git commit -a") 
    $ git commit -a -m "modification to gitosis.conf to list a new repository. Admin-access only"
    [master ######] modification to gitosis.conf to list a new repository. Admin-access only
    1 files changed, 1 insertions(+), 1 deletions(-)
    $ git push
    Counting objects: 5, done.
    Delta compression using 2 threads.
    Compressing objects: 100% (3/3), done.
    Writing objects: 100% (3/3), 399 bytes, done.
    Total 3 (delta 0), reused 0 (delta 0)
    To git@YOUR_SERVER:gitosis-admin.git   
       ######..######  master -> master


    So now gitosis knows about this new repo so now we need to make it. In a different directory:

    $ mkdir test_repo
    $ cd test_repo
    $ git init
    $ git remote add origin git@YOUR_SERVER:test_repo.git
    $ touch TEST_FILE
    $ git add TEST_FILE
    $ git commit -a -m "initial seed of test_repo"
    $ git push origin master:refs/heads/master

    and its done, "test_repo" now exist to be cloned (git clone git@YOUR_SERVER:test_repo.git). However, at the moment only the owner of sshkey: admin@localhost is able to clone,push or pull. If you are the only one that will ever clone, push or pull then continuing to add new repo's to the writable section of the [group gitosis-admin] is perfectly fine. But what if other people want to interact with your repositories?


    • To create a new repo first list it in a writable section of a gitosis group
    • push the new gitosis.conf to origin
    • create a git repo locally (git init, git commit...
    • setup this local git repo with correct remote repo details


    User Management

    User access is managed via gitosis.conf [group ] codeblocks as well as keydir/ ssh keys. Say someone called Alice would like to be able to view the code you commit to your test_repo. You can either make the repo publicly accessible or bring Alice under gitosis management. She would pass onto you an id_rsa.pub ssh keyfile. This needs to go into gitosis-admin/keydir/ so that gitosis is aware of Alice's uniqueID. 1st thing that needs to be done is rename this file to something more unique. ssh rsa keys tend to append the id_rsa file with USERNAME@HOSTNAME so:

    mv id_rsa.pub "$( cut -d' ' -f3 id_rsa.pub ).pub"

    will rename the id_rsa file to something more related to the id_rsa.pub origin lets assume this new file is called alice@somehost.pub This file needs to be moved to gitosis-admin/keydir/. At the moment our gitosis.conf looks like


    [group gitosis-admin]
    writable = gitosis-admin test_repo
    members = admin@localhost

    We now need to add alice to gitosis.conf BUT so she only has read-only access to test_repo. Todo this a new group will be needed

    [group gitosis-admin]
    writable = gitosis-admin test_repo
    members = admin@localhost 
    [group read-only]
    readonly = test_repo
    members = alice@somehost

    Now these modifications need to be added and pushed back to the origin

    $ git status
    # On branch master
    # Changed but not updated:
    #   (use "git add <file>..."; to update what will be committed)
    #   (use "git checkout -- <file>..." to discard changes in working directory)
    # modified:   gitosis.conf # # Untracked files:
    #   (use "git add <file>..."; to include in what will be committed)
    # keydir/alice@somehost.pub no changes added to commit (use "git add" and/or "git commit -a") 
    $ git add keydir/alice\@somehost.pub
    $ git commit -a -m "added alice@somehost key & gave read-only (clone&pull) access to repo: test_repo"
    [master ######] added alice@somehost key & gave read-only (clone&pull) access to repo: test_repo 
    1 files changed, 4 insertions(+), 0 deletions(-) 
    create mode 100644 keydir/alice@somehost.pub
    $ git push
    Counting objects: 8, done.
    Delta compression using 2 threads.
    Compressing objects: 100% (4/4), done.
    Writing objects: 100% (5/5), 547 bytes, done.
    Total 5 (delta 0), reused 0 (delta 0) To git@YOUR_SERVER:gitosis-admin.git   
       ######..######  master -> master

    Alice will now be able to clone via git clone git@YOUR_SERVER:test_repo.git


    • User management is via ssh keys
    • individual user ssh keys reside in the keydir/ directory
    • the filename of the ssh (minus extension .pub) is what is used to reference users within the gitosis.conf file
    • users can be listed in more then one group within gitosis.conf to align their access rights to each project



    Further gitosis.conf editing

    * add further examples for groups * description about the other sections available in gitosis.conf * details of howto make a repo publically clonable


    1) keys stored in keydir CANNOT have underscore ( _ ) in their name

    2) keys stored in keydir will warn about having at symbol ( @ ) in their name (may turn into an error

    3) named ssh keys

    Not yet rated