přihlášení | pravidla | SSH | základy | sdílení | e-mailové odpovědi | skupiny | GitLab CI | odkazy

GitLab

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.

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ří.

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.

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íčů.

Pravidla používání

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 UN*X systémy.

Vytvoření SSH klíče

Program ssh-keygen pri vytváření klíče můž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_ke_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_ke_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ěr žá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.

Základy používání

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.

Skupiny

Funkce vytváření vlastních skupin je v GitLabu vypnuta, aby nemohlo dojít ke kolizi se synchronizovanými skupinami. Pokud potřebujete vytvořit vlastní skupinu nebo chcete povolit synchronizaci skupiny, kontaktujte správce.

GitLab vám pošle e-mail, pokud se stanete členem některé skupiny.

Pokyny pro vlastníky synchronizovaných skupin

V žádosti o vytvoření skupiny uveďte

Pro předmětovou skupinu se studenty doporučujeme oprávnění Reporter, pro ostatní Developer. Práva pak lze upravovat v GitLabu pro jednotlivé uživatele zvlášť.

Pro skupiny, které jsou synchronizovány s Fakultní administrativou platí speciální omezení pro právo Owner. Synchronizační skript toto právo uděluje pouze správcům. Pokud běžnému členovi udělíte toto právo, po synchronizaci o něj přijde.

Nastavení skupiny

Pokud vám bylo uděleno právo vlastníka skupiny, GitLab vám umožní měnit její nastavení. Můžete změnit název nebo popis, ale v žádnem případě neměňte cestu (path). Technicky nelze v GitLabu tuto možnost zakázat, nicméně může způsobit konflikty při synchronizaci nových skupin.

Skupiny jsou implicitně synchronizovány s viditelností Private. Toto nastavení lze změnit na Internal nebo Public v SettingsGroup Visibility.

GitLab Continuous Integration

GitLab Continuous Integration (CI) slouží k automatizaci některých úkolů při vývoji v repozitáři, nejčastěji pro automatické jednotkové testování. Pro použití GitLab CI lze nakonfigurovat svůj vlastní fyzický nebo virtuální stroj (viz virtualizace Stratus.FI). Navíc lze také použít fakultní stroj gitlab-ci.fi.muni.cz.

Shrnutí

Fakultní gitlab-ci.fi používá oficiální GitLab Runner s kontejnerovou izolací ve službě Docker. Po spuštění nového úkolu (např. po git push do repozitáře) GitLab Runner požádá Docker o vytvoření nového kontejneru z obrazu, který je deklarován v repozitáři v souboru .gitlab-ci.yml. Do kontejneru se naklonuje repozitář a spustí se úkoly popsané ve zmíněném souboru. Po skončení se kontejner zruší a výsledek se vrátí GitLabu, který jej zobrazí v sekci CI/CD.

Konfigurace projektu pro gitlab-ci.fi.muni.cz

Nejdříve si přečtěte úvodní informace pro používání GitLab CI/CD. Dále budete potřebovat dokumentaci ke .gitlab-ci.yml.

Docker je nakonfigurován tak, aby neinstaloval automaticky všechny požadované obrazy, ale používal pouze ty lokálně dostupné. Tímto způsobem se zamezí nadměrnému instalování různých verzí obrazů, které by rychle zaplnili diskovou kapacitu stroje.

Aktuálně jsou dostupné tyto obrazy z DockerHub:

Repozitář Značky
oficiální alpine latest 3.7
oficiální gcc latest 7.3 7
oficiální haskell latest 8.2 8
oficiální maven latest 3.5.0-jdk-8 3-jdk-8 3-jdk-9
oficiální openjdk latest 8-jdk 9-jdk
oficiální ruby latest 2.4.2 2.5.0 2.5
jhasse/clang-tidy latest
amardikian/clang-3.8 latest
rsmmr/clang latest

Používaný obraz se deklaruje v .gitlab-ci.yml konfiguraci jako hodnota klíče image. Formát je buď REPOSITORY:TAG nebo REPOSITORY (výchozí značka se pak použije latest). Pokud nezadáte žádný obraz, použije se alpine:latest.

image: maven:latest

Pokud je to možné, používejte obrazy se značkou latest nebo alespoň co nejobecnější verzi (např. 3-jdk-8 místo 3.5.0-jdk-8). V případe aktualizace obrazů budou totiž starší verze smazány, pokud bude docházet volné místo na disku.

Aby se stroj nezatěžoval úkoly z repozitářů, které mají nastavené vlastní CI, akceptuje gitlab-ci.fi úkoly pouze z těch projektů, které jsou označené značkou shared-fi, což lze nastavit následovně:

Ve fakultním GitLab FI se můžete podívat do projektu unix/ci-examples, kde naleznete příklady konfigurace CI pro jednoduché projekty.

Instalace dalších obrazů

O instalaci dalších obrazů nebo verzí žádejte na adrese unix@fi.muni.cz, kde uveďte, k čemu budete obraz používat.

Pokud chcete nainstalovat vlastní nebo upravený obraz, přiložte k žádosti navíc i Dockerfile a všechny potřebné soubory pro sestavení obrazu. Správci obraz sestaví a nainstalují do Dockeru.

Další odkazy a návody