GitLab FI

GitLab je webový manažer Git repozitářů, podobný známé službě GitHub. Kromě správy repozitářů (které se zde nazývají projekty) umí GitLab zejména také Wiki a Issue tracking.

Pravidla používání

Přihlášení

Pokud máte na Fakultě informatiky aktivní účet, můžete se přihlásit pomocí LDAP autentizace na následujícím URL:

https://gitlab.fi.muni.cz/

Zadejte svůj fakultní login a heslo, účet se po prvním přihlášení automaticky vytvoří.

Další možnosti přihlášení

bez nutnosti zadávat heslo

SSH klíč
Kerberos SPNEGO

Externí účty

GitLab umožňuje vytvářet typ účtů, které nemohou vlastnit ani vytvářet projekty. Mohou pouze přispívat do projektů, ke kterým dostanou explicitní přístup. Tyto účty se označují jako externí. Je možné je využít pro zpřístupnění projektů výzkumníkům a kolegům z jiných institucí, oponentům nebo konzultantům závěrečných prací atd.

Správa externích účtů

Vytvářet externí účty není možné přímo v GitLab FI, zaměstnanci FI (členové skupiny fi-int) však mohou vytvářet, spravovat a blokovat externí účty v aplikaci na správu externích účtů ve Fakultní administrativě. Dokumentaci a nápovědu naleznete přímo v aplikaci.

Platnost účtu

Účet v GitLabu spojený s fakultním účtem je platný pouze pokud je fakultní účet aktivní a neblokovaný. Pokud dojde k zablokování nebo ukončení platnosti fakultního účtu, zablokuje se také přístup do GitLabu včetně SSH klíčů.

SSH klíč

Pokud chcete pracovat s repozitářem ze svého počítače bez nutnosti pokaždé zadávat heslo, můžete si do svého profilu nahrát veřejný SSH klíč. Postupujte podle návodu, zde uvedeme pouze tipy zejména pro linuxové systémy.

Vytvoření SSH klíče

Program ssh-keygen může během vytváření klíče požádat o zadání hesla. Není to povinné, použití klíče bez hesla je pak jednodušší, nicméně bezpečnější je klíč s heslem.

Použití klíče bez hesla

Otestovat funkčnost klíče můžete příkazem 

ssh -i $cesta_k_PRIVATNIMU_klici git@gitlab.fi.muni.cz

Výstup příkazu by měl být podobný následujícímu: 

Welcome to GitLab, (Jmeno, Prijmeni)
Connection to gitlab.fi.muni.cz closed.

Přidejte následující řádky do ~/.ssh/config (soubor nemusí dosud existovat): 

Host gitlab gitlab.fi.muni.cz
    HostName gitlab.fi.muni.cz
    IdentityFile cesta_k_PRIVATNIMU_klici

Význam jednotlivých řádků viz ssh_config(5). Vyzkoušejte, že příkaz ssh git@gitlab má stejný výstup jako výše i bez explicitního uvedení klíče.

Použití klíče s heslem

Pokud tento typ klíče budete používat jako by byl bez hesla, bude každá operace s GitLabem požadovat heslo ke klíči, což nepřináší téměř žádné výhody oproti běžnému přihlašování. S pomocí SSH agenta lze klíč odemknout pouze jednou a pak používat opakovaně: 

ssh-agent $SHELL
ssh-add ~/.ssh/id_gitlab

První příkaz spustí agenta, který pak spustí nový shell z proměnné $SHELL. Pokud váš shell tuto proměnnou nenastavuje, zadejte místo ní cestu k programu (např. /bin/sh). Ukončením shellu se ukončí i agent. Více informací o příkazech viz manuálové stránky pro ssh-agent(1) a ssh-add(1).

Pozor, ve starší verzi této dokumentace a na různých diskuzních fórech lze najít postup, který používá příkaz eval $(ssh-agent -c) nebo jemu podobný. Nedoporučujeme tento postup používat, protože nezaručuje korektní ukončení agenta.

Kerberos

GitLab umožňuje přihlášení do rozhraní a klonování repozitářů pomocí Kerberos tiketů.

Použití na stanicích Nymfe a Musa

Po přihlášení do grafického prostředí počítačů nymfe* nebo musa* uživatel automaticky obdrží Kerberos tiket, což lze ověřit příkazem klist: 

login@nymfe01:~$ klist
Ticket cache: FILE:/tmp/krb5cc_15291
Default principal: login@FI.MUNI.CZ

Valid starting       Expires              Service principal
12/17/2019 16:16:56  12/18/2019 16:16:51  krbtgt/FI.MUNI.CZ@FI.MUNI.CZ

  • Přihlášení

    Při přihlašování v prohlížečích Mozilla Firefox a Google Chrome (resp. Chromium) lze s platným tiketem použít tlačítko Kerberos Spnego místo zadávání hesla.
    GitLab Spnego

  • Klonování

    Při klonování repozitáře použijte adresu z Clone with KRB5.
    GitLab KRB5 clone

  • Synchronizace

    Příkazy git pull a git push budou také fungovat bez hesla s platným tiketem.

Tip
O tiket lze požádat explicitně příkazem kinit. To může být užitečné při vzdáleném SSH přístupu s autentizací SSH klíčem (např. na Aisu), kdy se tiket automaticky nevytváří.

Použití ze serverů Aisa, Anxur nebo Aura

Tento přihlašovací mechanizmus lze obecně použít i z jiných UNIXových strojů, na kterých je Kerberos pro doménu FI.MUNI.CZ nakonfigurovaný.

  • Přihlášení

    1. Přihlášení heslem

    Pokud při přihlašování na server zadáváte heslo, pak byste měli mít hned k dispozici tiket. Vyzkoušejte příkaz: 

    login@aisa$ klist

    2. Přihlášení bez hesla

    Přihlášení bez hesla (např. pomocí SSH klíče) tiket nevytvoří. Pokud žádný jiný nemáte, napište příkaz: 

    login@aisa$ kinit

    Po zadání hesla ověřte pomocí klist, že tiket máte.

  • Práce s Gitem

    Teď můžete v Gitu používat operace, které pracují s Kerberos autentizací (Klonování a Synchronizace výše).

  • Obnovení tiketu

    Pokud platnost tiketu vyprší, operace přestanou fungovat. Z bezpečnostních důvodů GitLab pro každý neautorizovaný přístup hlásí neexistující repozitář (i když ve skutečnosti existuje), proto může být chybová zpráva trochu nečekaná.

    Každopádně zkontrolujte pomocí klist, že máte platný tiket, a pokud ne, vytvořte si nový příkazem kinit.

Nastavení vlastního počítače

Tuto možnost lze využít jenom pro stroje v sítí FI. Viz také Omezení přístupu do sítě FI.

  • Kerberos

    Pro použití Kerberos autentizace na vlastním počítači musíte mít nainstalované nástroje pro tento autentizační mechanizmus, např. z balíků krb5-user (Ubuntu, Debian) nebo krb5-workstation (RHEL, CentOS, Fedora). Pro získání tiketu použijte příkaz: 
    user@machine:~$ kinit login@FI.MUNI.CZ

  • Git

    Git při klonování a synchronizaci může požadovat zadávání hesla, což při autentizaci Kerberem skončí chybou HTTP Basic: Access denied.
    Toto lze vyřešit následujícím příkazem: 
    # nastavení pro uživatele
user@machine:~$ git config --global http.emptyAuth true
# nastavení pro celý systém
user@machine:~$ sudo git config --system http.emptyAuth true

  • Mozilla Firefox

    Zadejte do adresního řádku about:config. V konfiguraci vyhledejte klíč network.negotiate-auth.trusted-uris a přidejte hodnotu fi.muni.cz.

  • Chromium

    Prohlížeč spusťte s parametrem --auth-server-whitelist=*.fi.muni.cz. Může být užitečné vytvořit si vlastní skript, který Chromium s tímto parametrem spustí, a umístit ho do /usr/local/bin.

Dokumentace služeb a funkcí

Dokumentaci k funkcím GitLabu naleznete na stránce nápovědy. Zejména doporučujeme

Sdílení repozitáře

Pokud chcete zpřístupnit repozitář dalším lidem nad rámec "viditelnosti" projektu (Private, Internal nebo Public), můžete je nastavit jako členy (members) projektu, viz přidávání členů.

Pokud chcete zpřístupnit privátní nebo interní projekt osobě bez fakultního účtu a dané osobě stačí pouze přístup pro stáhnutí projektu (tj. nepotřebuje přístup k Issues, wiki atd.), můžete použít Deploy keys (v podstatě read-only přístup k projektu pomocí SSH klíče). Pokud se požaduje přístup k dalším službám nebo možnost do projektu přispívat, musí se projekt zveřejnit nebo se musí pro osobu vytvořit externí účet (žádejte u správců).

E-mailové odpovědi

Fakultní GitLab má povolenou funkci Reply by E-mail, která umožňuje odpovídat na komentáře, "issues" a "milestones" přímo e-mailem. Pro správné fungování je však důležité dodržet několik pravidel:

V e-mailu lze používat Markdown a lze přidat přílohy, ty se pak objeví jako přílohy v odpovědi v GitLabu.

Zálohování

Git Repozitáře

Repozitáře uživatelů i skupin se pravidelně automaticky zálohují jako git bundles. Zálohování probíhá každý den brzo ráno. O obnovu omylem smazaného repozitáře žádejte na adrese gitlab@fi.muni.cz.

Repozitář obvykle nelze obnovit přímo do GitLabu, ale poskytneme bundle s plnou zálohou a případně další soubory s inkrementální zálohou. Tuto zálohu je možné obnovit následujícím způsobem:

  • Soubory

    Předpokládejme plnou zálohu v souboru repo.9RhwIP.0.bundle a dvě inkrementální zálohy v souborech repo.9RhwIP.1.bundle a repo.9RhwIP.2.bundle.

  • Obnova plné zálohy

    Vytvořte klon repozitáře z plné zálohy do adresáře repo: 
    git clone --mirror repo.9RhwIP.0.bundle repo

  • Inkrementální zálohy

    Plnou zálohu přesuňte, abyste mohli použít cyklus: 
    mv -i repo.9RhwIP.0.bundle repo.9RhwIP.bundle
    Obnovte inkrementální zálohy: 
    for bundle in repo.9RhwIP.*.bundle; do
    git -C repo remote set-url origin "${PWD}/${bundle}"
    git -C repo remote update
done

  • Obnova do GitLab FI

    Pokud chcete repozitář vrátit do GitLab FI, vytvořte pro něj nový projekt a spusťte následující příkazy: 
    git -C repo remote set-url origin ${url_repozitáře}
git -C repo push --all
git -C repo push --tags
Wiki stránky projektů jsou taky uložené jako Git repozitáře a lze je tedy obnovit ze záloh podobným způsobem.

Issues, Milestones, …

Ostatní součásti projektů (např. Issues) se zálohují spolu s databází GitLabu. Obnova těchto záloh je však náročná a lze obnovit pouze celkový stav databáze.

Z toho důvodu tyto zálohy slouží pouze pro účely obnovy při celkovém výpadku. Kompletní obnova individuálních projektů (kromě repozitářů, viz výše) není možná.

Pro informace o zálohování dalších systémů vizte dokument Zálohování na FI.

Další zajímavé funkce

Fakulta informatiky má licenci pro verzi GitLab Ultimate, které obsahuje všechny možnosti včetně Starter a Premium verzí. Na odkazované stránce naleznete výčet a porovnání verzí. Z těchto by pro uživatele na Fakultě informatiky mohli být zajímavé následující:

Další odkazy a návody