This is an in-progress translation.
To help translate the book, please fork the book at GitHub and push your contributions.

Gitolite

Let op: de laatste versie van deze sectie van het Progit boek is altijd beschikbaar in gitolite documentation. De auteur wil ook nederig vaststellen dat, ondanks dat deze sectie accuraat is, en kan (en vaak is) gebruikt worden om gitolite te installeren zonder verdere documentatie te lezen; het uit noodzaak niet compleet is, en niet de enorme hoeveelheid documentatie die bij gitolite komt kan vervangen.

Git is erg populair geworden in bedrijfsomgevingen, die veelal extra eisen hebben in termen van toegangscontrole. Gitolite was oorspronkelijk gemaakt om met die eisen te helpen, maar het blijkt dat het net zo bruikbaar is in de open source wereld: het Fedora project beheert de toegang tot hun pakket beheer repositories (ongeveer 10.000 stuks!) met behulp van gitolite, en dit is waarschijnlijk ook de grootste gitolite installatie.

Gitolite staat je toe om de toegang niet alleen per repository te specificeren, maar ook per branch of tag binnen elk repository. Dat wil zeggen dat je in kunt stellen dat bepaalde mensen (of groepen van mensen) alleen kunnen pushen naar bepaalde “refs” (branches of tags), maar niet naar andere.

Installeren

Het installeren van Gitolite is erg eenvoudig, zelfs als je niet alle uitgebreide documentatie leest die erbij zit. Je hebt een account om een of andere Unix server nodig; diverse Linux smaken en Solaris 10 zijn getest. Je hebt geen root toegang nodig, aangenomen dat git, perl, en een met openssh verenigbare server reeds geïnstalleerd zijn. In de voorbeelden hieronder zullen we het gitolite account gebruiken op een host genaamd gitserver.

Gitolite is wat ongebruikelijk voor wat betreft “server” software – toegang gaat via ssh, en dus is ieder gebuikers id een potentiële “gitolite host”. Bij gevolg zijn er begrippen als het “installeren” van de software, en dan het “instellen” van een gebruiker als een “gitolite host”.

Gitolite kan op 4 manieren geïnstalleerd worden. Mensen die Fedora of Debian systemen gebruiken, kunnen een RPM of DEB krijgen en dat installeren. Mensen met root toegang kunnen het handmatig installeren. Bij deze twee methoden kan iedere gebruiker op het systeem een “gitolite host” worden.

Mensen zonder root toegang kunnen het binnen hun eigen gebruikerid installeren. Tenslotte kan gitolite geïnstalleerd worden door het uitvoeren van een script op het werkstation, vanuit een bash shell. (Zelfs de bash shell die bij msysgit zit voldoet, mocht je het je afvragen).

We zullen deze laatste methode in dit artikel beschrijven; kijk alstublieft in de documentatie voor de andere methoden.

Je begint met het verkrijgen van toegang op je server op basis van een publieke sleutel, zodat je in kunt loggen vanaf je werkstation zonder een wachtwoord prompt te krijgen. De volgende methode werkt op Linux; voor andere werkstation OSsen zul je dit misschien handmatig moeten doen. We gaan er vanuit dat je reeds een sleutelpaar gegeneerd hebt met behulp van ssh-keygen.

$ ssh-copy-id -i ~/.ssh/id_rsa gitolite@gitserver

Dit zal je vragen naar het wachtwoord van het gitolite account, en dan toegang met een publieke sleutel instellen. Dit is essentieel voor het installatiescript, dus controleer dat je een commando kan uitvoeren zonder een wachtwoord prompt te krijgen:

$ ssh gitolite@gitserver pwd
/home/gitolite

Vervolgens clone je Gitolite van de hoofdsite van het project en voer je het “easy install” script uit (het derde argument is de naam zoals je wilt verschijnen in het resulterende gitolite-admin repository):

$ git clone git://github.com/sitaramc/gitolite
$ cd gitolite/src
$ ./gl-easy-install -q gitolite gitserver sitaram

En dan ben je klaar! Gitolite is nu geïnstalleerd op de server, en je hebt nu een splinternieuw repository genaamd gitolite-admin in de home directory van je werkstation. Je kunt je gitolite installatie beheren door wijzigingen te doen in dit repository en te pushen.

Dat laatste commando zorgt wel voor een flinke hoeveelheid uitvoer, dat interessant kan zijn om te lezen. Daarnaast wordt de eerste keer dat je dit uitvoert een nieuw sleutelpaar gegenereerd; je zult hiervoor een wachtzin moeten kiezen of enter drukken om zonder te werken. Waarom een tweede paar nodig is, en hoe het gebruikt wordt, wordt uitgelegd in het “ssh troubleshooting” document dat bij Gitolite zit. (He, de documentatie moet toch ergens goed voor zijn!)

Standaard worden de testing en gitolite-admin repositories aangemaakt. Als je een van deze lokaal wilt clonen (vanaf een account dat SSH console toegang heeft tot het gitolite account via authorized_keys), type:

$ git clone gitolite:gitolite-admin
$ git clone gitolite:testing

Om dezelfde repos van ieder ander account te clonen:

$ git clone gitolite@servername:gitolite-admin
$ git clone gitolite@servername:testing

De installatie aanpassen

Hoewel de standaard, snelle, installatie voor de meeste mensen werkt, zijn er manieren om de installatie aan te passen als dat nodig is. Als je het -q argument weglaat, krijg je een “spraakzame” installatiemodus – met gedetailleerde informatie van wat de installatie aan het doen is bij iedere stap. De spraakzame modus laat je ook bepaalde parameters van de server-kant instellen, zoals de locatie van de echte repositories, door een “rc” bestand dat de server gebruikt aan te passen. Dit “rc” bestand is behoorlijk van commentaar voorzien, dus je zou eenvoudig in staat moeten zijn om de wijzigingen te maken die je wilt, op te slaan, en te vervolgen. Dit bestand bevat ook instellingen die je kunt aanpassen om sommige geavanceerde opties van gitolite aan of uit te zetten.

Configuratiebestand en Toegangsregels

Als de installatie klaar is, kun je wijzigen naar het gitolite-admin repository (dat in je HOME directory geplaatst is) en er in rondkijken om te zien wat je hebt:

$ cd ~/gitolite-admin/
$ ls
conf/  keydir/
$ find conf keydir -type f
conf/gitolite.conf
keydir/sitaram.pub
$ cat conf/gitolite.conf
#gitolite conf
# please see conf/example.conf for details on syntax and features

repo gitolite-admin
    RW+                 = sitaram

repo testing
    RW+                 = @all

Let op dat “sitaram” (het laatste argument voor het gl-easy-install commando dat je eerder invoerde) lees- en schrijftoegang heeft op het gitolite-admin repository, en een publieke sleutelbestand heeft met dezelfde naam.

De syntax voor het gitolite configuratie bestand is ruim beschreven in conf/example.conf, dus daarom noemen we hier alleen de hoogtepunten.

Je kunt voor het gemak gebruikers of repos groeperen. De groepnamen zijn net als macros; als je ze definieert, maakt het niet eens uit of ze projecten zijn of gebruikers; dat onderscheid wordt alleen gemaakt als je de “macro” gebruikt.

@oss_repos      = linux perl rakudo git gitolite
@secret_repos   = fenestra pear

@admins         = scott     # Adams, not Chacon, sorry :)
@interns        = ashok     # get the spelling right, Scott!
@engineers      = sitaram dilbert wally alice
@staff          = @admins @engineers @interns

Je kunt permissies instellen op “ref” niveau. In het volgende voorbeeld mogen stagiaires alleen naar de “int” branch pushen. Engineers mogen pushen naar iedere branch waarvan de naam begint met “eng-“, en tags die beginnen met “rc” gevolgd door een cijfer. En de admins mogen alles (inclusief rewind) doen op iedere ref.

repo @oss_repos
    RW  int$                = @interns
    RW  eng-                = @engineers
    RW  refs/tags/rc[0-9]   = @engineers
    RW+                     = @admins

De expressie achter de RW of RW+ is een reguliere expressie (regex), waarmee de ref naam (ref) waarnaar gepushed wordt, wordt gecontroleerd. Dus daarom noemen we het een “refex”! Natuurlijk kan een refex veel krachtiger zijn dan hier getoond wordt, dus overdrijf niet als je niet op je gemak bent met perl regexen.

En, zoals je waarschijnlijk al geraden had, zet Gitolite refs/heads/ er als een syntactisch gemak voor als de refex niet begint met refs/.

Een belangrijke eigenschap van de syntax van het configuratiebestand is dat niet alle regels voor een repository op een plaats moeten staan. Je kunt alle overeenkomstige dingen bij elkaar houden, zoals alle regels voor oss_repos die hierboven getoond wordt, en dan specifieke regels voor specifieke gevallen verderop toevoegen, zoals:

repo gitolite
    RW+                     = sitaram

Die regel zal alleen maar toegevoegd worden aan de set regels voor het gitolite repository.

Op dit punt zul je je misschien afvragen hoe de toegangsregels feitelijk toegepast worden, dus laten we dat kort bespreken.

Er zijn twee lagen van toegang in gitolite. De eerste is op het niveau van het repository; als je lees (of schrijf) toegang hebt op een ref in het repository, dan heb je lees (of schrijf) toegang tot het repository.

De tweede laag, die alleen van toepassing is op “schrijf” toegang, is per branch of tag binnen een repository. De gebruikersnaam, de toegang die geprobeerd wordt (W of +), en de refnaam die aangepast wordt zijn bekend. De toegangsregels worden nagekeken in volgorde van verschijning in het configuratiebestand, waarbij gezocht wordt naar een passende vergelijking voor deze combinatie (maar onthoudt dan de refnaam gepast wordt met een regex, niet slechts met tekst). Als een overeenkomst gevonden wordt, dan slaagt de push. Als de vergelijking er doorheen valt wordt toegang geweigerd.

Geavanceerde Toegangscontrole met “afwijzing” regels

Tot dusver hebben we alleen permissies gezien die R, RW, of RW+ zijn. Maar, gitolite staat ook een andere permissie toe: -, wat voor “afwijzing” staat. Dit geeft je veel meer kracht, ten koste van wat complexiteit, omdat nu er doorheen vallen niet de enige manier is waarop toegang geweigerd wordt, de volgorde van de regels doet er nu ook toe!

Stel dat we in bovenstaande situatie willen toestaan dat engineers alle branches behalve master en integ mogen terugdraaien. Zo doe je dat:

    RW  master integ    = @engineers
    -   master integ    = @engineers
    RW+                 = @engineers

Nogmaals, je volgt eenvoudig de regels vanaf de bovenkant totdat je een overeenkomst vindt voor je toegangsmodus, of een afwijzing. Een push zonder rewind op master of integ wordt toegestaan door de eerste regel. Een rewind push naar die refs komt niet overeen met de eerste regel, valt door naar de tweede, en wordt daarom afgewezen. Iedere push (rewind of non-rewind) naar refs anders dan master of integ zal sowieso niet overeenkomen met de eerste twee regels, en de derde regel staat het toe.

Pushen beperken per gewijzigde bestanden

Naast het beperken van de branches waar een gebruiker wijzigingen naar kan pushen, kun je ook de bestanden die ze aan mogen raken beperken. Bijvoorbeeld, stel dat de Makefile (of een ander programma) eigenlijk niet door iedereen gewijzigd mag worden, omdat er een hoop dingen vanaf hangen of kapot gaan als de wijzigingen niet precies goed gedaan worden. Je kunt het gitolite vertellen:

repo foo
    RW                  =   @junior_devs @senior_devs

    RW  NAME/           =   @senior_devs
    -   NAME/Makefile   =   @junior_devs
    RW  NAME/           =   @junior_devs

Deze krachtige eigenschap is gedocumenteerd in conf/example.conf.

Persoonlijke Branches

Gitolite heeft ook een eigenschap genaamd “persoonlijke branches” (of liever, “persoonlijke branch naamruimte (namespace)” die heel handig kan zijn in een bedrijfsomgeving.

Veel van de code uitwisseling die gedaan wordt in de git wereld gebeurd door middel van “pull alstublieft” verzoeken. In een bedrijfsomgeving echter is ongeverifieerde toegang een no-no, een werkstation van een ontwikkelaar kan geen verificatie doen, dus je zult naar de centrale server moeten pushen en iemand moeten vragen om vanaf daar te pullen.

Dit zou doorgaans dezelfde branchnaam vervuiling veroorzaken als in een gecentraliseerd VCS, en het instellen van permissies hiervoor wordt een klus voor de admin.

Gitolite staat je toe een “personal” of “scratch” naamruimte prefix voor iedere ontwikkelaar te definiëren (bijvoorbeeld, refs/personal/<devname>/*); zie de “personal branches” sectie in doc/3-faq-tips-etc.mkd voor details.

“Wildcard” repositories

Gitolite staat je toe om repositories met wildcards (eigenlijk perl regexen) te specificeren, zoals bijvoorbeeld assignments/s[0-9][0-9]/a[0-9][0-9], als willekeurig voorbeeld. Dit is een zeer krachtige eigenschap, dat aan gezet moet worden door $GL_WILDREPOS = 1; in het rc bestand in te stellen. Het staat je toe om een nieuwe permissie modus (”C”) toe te wijzen, die gebruikers toestaat om repositories op basis van die wildcards aan te maken, waarbij automatisch eigendom toegewezen wordt aan de gebruiker die het aangemaakt heeft, hem/haar toestaat R en RW permissies aan andere gebruikers uit te delen om samen te werken etc. Deze eigenschap is gedocumenteerd in doc/4-wildcard-repositories.mkd.

Andere Eigenschappen

We ronden deze bespreking af met een voorproefje van andere eigenschappen, die allemaal en nog vele meer, gedetailleerd zijn beschreven in de “faqs, tips, etc” en andere documenten.

Logging: Gitolite legt alle succesvolle toegangen vast. Als je wat rustiger bent over het geven van rewind toegang aan andere mensen (RW+) en een of ander joch heeft “master” opgeblazen, dan is het logbestand je redder, in termen van het eenvoudig en snel vinden van het SHA dat kapot is gegaan.

Git buiten normaal PATH: Een extreem bruikbare gemakseigenschap in gitolite is ondersteuning voor een git installatie buiten het normale $PATH (dit komt vaker voor dan je denkt; sommige bedrijfsomgevingen of zelfs sommige hosting providers weigeren dingen systeembreed te installeren en je eindigt uiteindelijk met het installeren in je eigen home mappen). Normaal gesproken wordt je geforceerd om de gebruikerskant git op een of andere manier bewust te maken van deze niet-standaard locatie van de git bestanden. Met gitolite, kies je slechts een spraakzame installatie en stelt $GIT_PATH in in de “rc” bestanden. Voor de rest zijn er daarna geen wijzigingen meer nodig aan de gebruikerskant :-)

Toegangsrapportage: Een andere handige eigenschap is wat er gebeurd als je probeert met SSH naar de server te gaan. Gitolite toont je welke repos je toegang tot hebt, en welke toegang dat is. Hier is een voorbeeld:

    hello sitaram, the gitolite version here is v1.5.4-19-ga3397d4
    the gitolite config gives you the following access:
         R     anu-wsd
         R     entrans
         R  W  git-notes
         R  W  gitolite
         R  W  gitolite-admin
         R     indic_web_input
         R     shreelipi_converter

Delegatie: Voor hele grote installaties, kun je verantwoordelijkheden voor groepen of repositories delegeren aan diverse personen, en ze die onderdelen onafhankelijk laten beheren. Dit beperkt de belasting op de hoofd beheerder, en maakt hem minder een flessenhals. Deze eigenschap heeft zijn eigen documentatiebestand in de doc/ map.

Gitweb ondersteuning: Gitolite ondersteund gitweb op meerdere manieren. Je kunt specificeren welke repos zichtbaar zijn via gitweb. Je kunt de “eigenaar” en “omschrijving” voor gitweb instellen in het gitolite configuratiebestand. Gitweb heeft een mechanisme voor je om toegangscontrole gebaseerd op HTTP verificatie te implementeren, dus je kunt het het “samengestelde” configuratiebestand laten gebruiken dat gitolite produceert, wat betekend dat dezelfde toegangsregels (voor leestoegang) van toepassing zijn op gitweb en gitolite.

Spiegeling: Gitolite kan je helpen met het onderhouden van meerdere spiegels, en er makkelijk tussen wisselen als de hoofdserver plat gaat.