gitolite

Gitolite je administrační systém pro správu git repozitářů založený na gitu

Administrace

Administrace systému gitolite se provádí prostřednictvím git repozitáře s názvem gitolite-admin Ten obsahuje dva podadresáře:

• keydir - adresář pro veřejné ssh klíče uživatelů
• conf - adresář pro konfigurační soubory

Hlavním konfiguračním souborem je soubor gitolite-admin/conf/gitolite.conf

• zakládání nových repozitářů
• přidávání uživatelů
• správa přístupu do repozitářů

Práva k dílčí administraci repozitářů (resp. skupinám repozitářů) lze delegovat pověřeným uživatelům

Správce

Uživatelé

Uživatelé se do systému přidávají tak, že se do adresáře keydir nakopíruje veřejný ssh klíč uživatele, uložený do souboru s příponou ".pub"

Název souboru podléhá následující konvenci:

uzivatel.pub
uzivatel@domain.cz.pub
uzivatel@domain.cz@desktop.pub

Jak si můžete povšimnout, uživatel může být identifikován nejenom přes pouhé uživatelské jméno, ale mailovou adresou. Je to proto, aby se usnadnila orientace v uživatelských jménech. Třetí varianta je určena pro případ, že jeden uživatel hodlá používat více veřejných klíčů. Např. pokud přistupuje z různých lokací pro každou z nich má vygenerovaný jiný veřejný klíč.

Gitolite používá několik systémově definovaných uživatelů: all - do skupiny all spadne každý anonymní uživatel - tj. uživatel bez platného ssh klíče gitweb - uživatel, pod kterým gitolite provádí úpravy konfigurace pro gitweb daemon - uživatel, pod kterým gitolite provádí úpravy konfigurace, které vyžaduje git-daemon

Repozitáře

Přidání a správa uživatelských přístupů do repozitářů se provádí tak, že se do konfiguračního souboru napíše napíše na řádek začínající kódem "repo" název adresáře a pod něj se přidá odsazený seznam s nastavením přístupových práv uživatelům

@skupina_uzivatelu = user1 user2 user3 repo nejaky_repozitar RW+ = delegovany_spravce RW = skupina_uzivatelu R = @all

Práva

R

Uživatel může repozitář pouze stáhnout

RW

Uživatel může repozitář stáhnout a může pushovat (uploadovat) nové verze

RW+

Jako RW, ale navíc může uživatel provádět tzv. non-fast forward push, tj. může modifikovat již exisující commity

Tato práva se dají aplikovat ne jen na celý repozitář, ale i na jeho jednotlivé větve a soubory/podadresáře.

Skupiny

Uživatele i repozitáře lze v konfiguraci seskupovat do skupin. Se skupinami se pak pracuje obdobným způsobem, jako by šlo o jeden repozitář, resp. jednoho uživatele.

Definice skupiny se provádí přidáním zavináče před jméno skupiny a přiřazením názvů repozitářů či jmen uživatelů, které má zastupovat

@skupina_uzivatelu = user1 user2 user3

Seskupovat lze pouze repozitáře nebo uživatele, nikoliv skupiny!

Delegovaná správa repozitářů

Delegování administrace - předání administrace k vybranému repozitáři či skupině repozitářů, se provádí tak že se všem uživatelům, na která mají být práva delegována nastaví k adresáři gitolite-admin právo RW.

A následně se jim "přidělí" práva k souborům do nichž budou zapisovat nastavení práv k repozitářům delegované skupiny. Tyto soubory, ani podadresář se netvoří automaticky, ale musí si je delegovaní uživatelé zakládat sami, po naklonování repozitáře gitolite-admin.

Delegovaná správa repozitářů znamená, že vybraní uživatelé mohou v rámci delegované skupiny již založených repozitářů spravovat přístupová práva uživatelům se zavedeným veřejným klíčem. Tzn. přidávat či odebírat přístup, nebo měnit úroveň přístupu. Na rozdíl od správce, (a uživatelů s právy RW+ pro repozitář gitolite-admin) delegovaní uživatelé nemohou importovat klíče, ani zakládat nové repozitáře.

Publikování git repozitáře přes www rozhraní

Aby byl repozitář vypublikován přes www rozhraní, musí být splněny následující podmínky:

1. K repozitáři (nebo skupině repozitářů) musí mít právo čtení (R) uživatel gitweb
2. Repozitář musí mít nastaven komentář (bez toho nedojde k jeho začlenění do souboru projects.list)

Právo pro uživatele gitweb lze nastavit i hromadně přes skupinu, ovšem komentář musí mít každý repozitář svůj vlastní

Instalace a základní konfigurace

Následující postup instalace a konfigurace gitolite je založen na distribučním balíku pro Debian ( aktuálně verze 1.5.3 ). V zásadě by však měl být použitelný na jakékoliv jiné linuxové distribuci.

Na počátku byla instalace potřebných balíků přes balíčkovací systém APT...

stroj:~# apt-get install gitolite libapache2-mod-perl2 gitweb

Vytvoření instance gitolite

Defakto každý uživatel s účtem na serveru a povoleným ssh přístupem založit vlastní instanci gitolite, ve které si pak bude moct tvořit a administrovat své vlastní git repozitáře.

Gitolite využívá pro přístup ssh. Pokud se do něj naimportuje stejný veřejný klíč jaký používá uživatel pro přihlašování k účtu, v jehož rámci je instance vytvořena, tak se již na normální konzoli tímto klíčem nepřihlásí! Místo toho se mu objeví hláška se seznamem jeho přístupových práv k repozitářům. Viz Příklad. user@z_klienta:~$ ssh gitadmin@stroj PTY allocation request failed on channel 0 hello gitadmin, the gitolite version here is 1.5.3-1 (Debian) the gitolite config gives you the following access: R W gitolite-admin @R @W testing Connection to 123.45.67.89 closed.

A nyní již k věci.

První den tedy Bůh stvořil uživatele. Dejme tomu, že mu dal jméno gitadmin. A protože věděl že pátý den bude oživovat webový přístup přes gitweb, přidal tohoto uživatele rovnou do skupiny www-data, tj. skupiny uživatele, pod kterým obvykle běží webový server Apache2. Pak šel chytat lelky protože do pátku je času dost.

stroj:~# adduser gitadmin
stroj:~# adduser www-data gitadmin

Druhý den uživatel gitadmin do svého účtu na stroj nakopíroval svůj veřejný ssh klíč (po vygenerování přes ssh-keygen bývá obvykle uložený v souboru ~/.ssh/id_rsa.pub), aby jej mohl následující den použít pro vytvoření vlastní instance gitolite.

Soubor s klíčem uložil do souboru s názvem ~/gitadmin.pub. V zásadě bylo úplně lhostejné kam a pod jakým názvem tento klíč nakopíruje. Podstatná informace je, že jeho název musel odpovídat budoucímu "username", pod kterým měl být klíč identifikován v pravidlech konfiguračního souboru gitolite.conf.

Třetí den čekala uživatele gitadmin hromada práce se správným nastavením gitolite a souborů nezbytných pro budoucí publikování adresářů přes www rozhraní...

Založení instance gitolite

Pro založení vlastní instance gitolite, spustil uživatel gitadmin ve svém domovském adresáři skript gl-setup. Jako parametr mu předal svůj veřejný klíč, který nakopíroval během předchozího dne.

gitadmin@stroj:~$ gl-setup ./gitadmin.pub

Skript gl-setup pak založil nezbytné soubory a adresáře:

• adresář ~/repositories pro repozitáře...
• v něm základní administrátorský repozitář ~/repositories/gitolite-admin.git
• demonstrační repozitář ~/repositories/testing.git
• soubor ~/projects.list pro jména repozitářů co jednou budou předhozeny plénu přes web
• skrytý adresář ~/.gitolite ( což není nic jiného než lehce přiohnutý, dobře známý adresář .git )
• a konfigurační soubor ~/.gitolite.rc pro jména repozitářů které bude gitweb házet přes web do pléna. Zatím je však prázdný.

Základní konfigurační nastavení

Skript gl-setup ale není vševědoucí jako Bůh, proto musel čtvrtý den uživatel gitadmin připravit adresáře a upravit konfigurační soubory, tak aby byly připraveny na okamžik kdy bude vzkříšen gitweb

Ve svém domovském adresáři...

1. Založil adresář ~/perl. Do něj symlinkem prolinkoval soubor /usr/lib/cgi-bin/gitweb.cgi pod jménem git
2. K sobě zkopíroval konfigurační soubor /etc/gitweb.conf, aby jej mohl upravit.
3. Souboru ~/projects.list změnil práva na 660 (aby z něj mohl číst také uživatel www-data)
4. A provedl úpravy těchto konfiguračních souborů...

Ve zkopírovaném souboru ~/gitweb.conf nahradil obsah proměnných..

• $projectroot - absolutní cestou ke svým repozitářům ( /home/gitadmin/repositories ).
• $projects_list - absolutní cestou k souboru /home/gitadmin/projects.list

Ve skrytém souboru ~/.gitolite.rc...

1. zakomentoval řádek na kterém se proměnné $REPO_UMASK přiřazuje hodnota 0077
2. a odkomentoval řádek následující, na kterém se proměnné $REPO_UMASK přiřazuje hodnota 0027

A odevzdal se do rukou božích..

Konfigurace webového rozhraní

Pátý den Bůh zvednul kosti z lenošky, a protože gitadmin byl konečně s přípravami hotov, jal se křísit gitweb.

Gitolite je pouze administrační systém, proto je pro publikaci vybraných repozitářů přes www rozhraní je třeba využít služeb webového serveru Apache2. Ten pro generování stránek publikovaných repozitářů volá perlovský skript gitweb. Protože webový server Apache2 tvoří řada instalačních balíků s nejrůznějšími moduly, je nejjednodušším způsobem jeho instalace přes distribuční balíkovací systém APT, jak již bylo uvedeno výše

gitweb přes libapache2-mod-perl2

Ve výchozím nastavení se spouští gitweb jako CGI skript. To by sebou mohlo nést určitá rizika a také to může více zatěžovat server. Proto je lepší změnit výchozí konfiguraci Apache2 tak aby se skript spouštěl přes perlovský modul perl. a modul cgid pro jistotu z konfigurace vyhodit.

Před úpravami..

• Konfigurační soubor /etc/gitweb.conf
• Konfigurační soubor /etc/apache2/conf.d/gitweb:

Alias /gitweb /usr/share/gitweb <Directory /usr/share/gitweb> Options FollowSymLinks +ExecCGI AddHandler cgi-script .cgi </Directory>

• Styly a ikony v adresáři /usr/share/gitweb
• Skript v adresáři /usr/lib/cgi-bin/gitweb.cgi

Co stvořil Bůh...

• Původní konfigurační soubor /etc/gitweb.conf nechal tam kde byl, protože v konfiguraci stejně přenastavil proměnnou GITWEB_CONFIG tak, aby vedla ke konfiguračnímu souboru uživatele gitadmin.
• Ovšem obsah konfiguračního soubor /etc/apache2/conf.d/gitweb změnil zásadně:

ScriptAlias /pub /home/gitadmin/perl <Location /pub> SetEnv GITWEB_CONFIG /home/gitadmin/gitweb.conf SetHandler perl-script PerlResponseHandler ModPerl::Registry Options +ExecCGI PerlSendHeader On Order allow,deny Allow from all </Location>

• Také vytvořil adresář /var/www/gitweb a do něj z adresáře /usr/share/gitweb prosymlinkoval styl a ikony, protože věděl že tam je bude nejspíš gitolite hledat, pokud k nim gitadmin ve svém konfiguračním souboru nezmění cestu.
• Přes a2dismod pak deaktivoval modul cgid. Při tom zkontroloval zda je zaveden modul perl. ( Pokud by nebyl, tak by jej musel přes a2enmod zavést )
• Vše završil restartováním Apache2

Protože v konfiguračním souboru pro Apache2 rozhodnul, že instance uživatele gitadmin bude schována za alias /pub, je adresa webového rozhraní pro veřejně publikované repozitáře uživatele gitadmin

http://stroj/pub/git

Tímto Bůh zakončil svůj pracovní týden a vykopnul uživatele gitadmin z ráje, ať se již nadále sám moří s administrací repozitářů, když po ní tolik toužil, nespokojen s pouhým delegováním práv.

Postinstalační postup na klientské straně

Ze rozběhaného serveru..

1. nejprve gitadmin naklonoval svou administrační repozitory gitolite-admin na klientskou stanici..
2. ..kde v souboru conf/gitolite.conf provedl potřebné úpravy pro založení a publikování nových repozitářů.
3. Nakopíroval do adresáře keydir/ veřejné ssh klíče dalším uživatelům (viz Administrace).
4. A po provedení všech potřebných úprav, přidal přes add tyto nové klíče do administračního repozitáře, uložil příkazem commit změny do lokální repozitory a pak přes push odeslal změny na server.

Tam gitolite provedl automaticky odpovídající změny - vytvořil repozitáře, uložil klíče, upravil příslušné soubory, etc.

user@stroj:~$ git clone gitadmin@git:gitolite-admin ... user@stroj:~$ cd gitolite-admin user@stroj:~$ git add . user@stroj:~$ git commit -a user@stroj:~$ git push

Založení dalších instancí gitolite

Postup je v zásadě stejný. Pouze se zopakuje pro jiného uživatele. Konfiguraci pro Apache2 lze přidat do stejného souboru, ale koncepčně lepší je pro každou instanci vytvořit samostatný konfigurační soubor.

Vytvoření samostatných instancí má smysl tehdy, pokud se uživatelé nechtějí spokojit pouze s delegováním práv, ale chtějí si také sami zakládat nové repozitáře a přidávat nové uživatele.

Přístup přes git server

Git démon není na našem serveru nainstalován.

Přístup na git repozitáře

Aby mohl uživatel provést první commit do nově založeného git repozitáře musí mít na serveru naimportován přes gitolite svůj veřejný klíč!

První commit projektu na server

1. Na serveru musí být založen repozitář projektu
2. Tento zatím prázdný repozitář se naklonuje na lokální stroj
3. Do prázdného adresáře projektu se nakopírují soubory, které mají být jeho součástí
4. Provede se první lokální commit
5. a následně se příkazem push --all odešlou na server.

Ukázka naklonování repozitáře accesscontrol.git ze stroje http://git.felk.cvut.cz

user@stroj:~$ git clone git@git.felk.cvut.cz:accesscontrol user@stroj:~$ ls accesscontrol user@stroj:~$ cd accesscontrol/ user@stroj:~/accesscontrol$ user@stroj:~/accesscontrol$ git push --all