GitLab integrace

0 Úvod

GitLab integrace je přídavný modul, který lze přidat do kteréhokoli ze tří plánů Easy Projectu.

Účelem tohoto přídavného modulu je agregovat důležitá data z GitLabu v Easy Projectu za účelem pomáhat s reportováním, hodnocením a prezentací vývojových aktivit, a tím podporovat rozhodování ze strany stakeholderů, kteří investují do projektů softwarového vývoje a firemních procesů.

Mezi jeho schopnosti patří velmi jednoduché počáteční připojení k vaší GitLab instanci (jak samostatně hostované, tak cloudové verze). Po navázání připojení zobrazí Easy Project nejdůležitější položky z GitLabu v konfigurovatelných a filtrovatelných seznamech (podobných seznamu úkolů). Mezi tyto položky (entity) patří:

Repozitáře
Merge requesty
Commity
Testy

včetně jejich nejdůležitějších atributů.

Klíčovým prvkem integrace je, že Easy Project NE-kopíruje repozitáře fyzicky. Kód zůstává v GitLabu.

1 Navazování spojení

Nejprve musíte mít přístupový token od uživatele GitLabu s příslušnými právy.

Vyberte uživatele, přes kterého bude Easy Project přistupovat ke GitLabu. Může se jednat o zvláštního uživatele, přes kterého se žádná osoba nepřihlásí, například er_integrator.
Upravte profil tohoto uživatele.
Přejděte do sekce Přístupové tokeny, vyberte všechna práva a klikněte na "Vytvořit osobní přístupový token".
Zkopírujte tento token.

Nyní můžete přejít do Easy Projectu a zadat klíčové údaje.
Přejděte do Administrace >> GitLab integrace >> Najděte Dostupné integrace a klikněte na Konfigurovat.
Pojmenujte své připojení, zadejte URL adresu a dříve vygenerovaný přístupový token.
Poznámka: V případě cloudu, např. https://gitlab.com/my-little-gitlab, stačí zadat https://gitlab.com/ bez sub-uri. Není třeba se obávat, můžete vidět pouze projekty, které vidí uživatel s přístupovým tokenem. Pokud všechny své projekty nastavíte jako soukromé, nikdo jiný je neuvidí.
Uložte.
A je to! Připojení je provedeno.

Vše ostatní se děje automaticky na pozadí. Zejména:

Easy Project načte všechny projekty/repozitáře, jejichž členem je uživatel s přístupovým tokenem.
V těchto repozitářích se vytvářejí webhooky => takže informace o nových commitech, merge requestech a testech budou odesílány do Easy Projectu.

1.1 Odstraňování problémů s připojením

Problém A
Nevidím žádné repozitáře z této GitLab instance
V důsledku nepředvídatelných okolností se může stát, že výše uvedené operace nebudou úspěšně provedeny. V důsledku toho nemusíte v Easy Projectu vidět žádné repozitáře z této GitLab instance.

V takovém případě můžete importovat repozitáře ručně pomocí několika kliknutí.

Přejděte do Administrace >> GitLab integrace >> Konfigurované integrace >> Klikněte na název
V postranní nabídce klikněte na Importovat.
Vyberte skupinu:
S GitLabem, který je hostován ve vlastní režii, zde bude skupina reprezentující celou instanci. Jako v příkladu ze screenshotu.
S cloudovým GitLabem uvidíte všechny veřejné skupiny a pravděpodobně budete muset svou skupinu vyhledat. Pole se automaticky doplňuje, takže vyhledávání je rychlé a snadné.
Po jejím výběru a odkliknutí se zobrazí seznam nalezených projektů/repozitářů.
Vyberte vše a klikněte na Importovat.

Problém B
Repozitáře byly nalezeny, ale moje nové commity, merge requesty a testy nebyly přidány do Easy Projectu

Nová data z GitLabu jsou odesílána do Easy Project prostřednictvím webhooků nakonfigurovaných v GitLabu. Za normálních okolností jsou vytvářeny automaticky. Můžete si to ověřit ve svém projektu GitLab >> Nastavení >> Webhooky

Pokud neexistuje webhook s odkazem na vaši aplikaci, budete jej muset vytvořit. Opět se jedná o jednoduchou operaci.

Přejděte do Administrace >> GitLab integrace >> Konfigurované integrace >> Klikněte na název
V postranní nabídce klikněte na Repozitáře
Klikněte na název jednoho
Klikněte na Registrovat všechny integrace

To ručně vynutí vytvoření webhooku ve správném tvaru.

2 Referenční klíčová slova

Nyní, když je nakonfigurováno obecné připojení, již máte informace z GitLabu v Easy Projectu a můžete je využít. Aby však bylo možné plně využít integraci, existuje několik dalších nastavení. Některé jsou již přednastaveny a můžete je pouze zkontrolovat.

Je možné připojovat konkrétní commity nebo merge requesty s konkrétními úkoly a dokonce tímto způsobem zaznamenávat čas, aniž byste museli navštívit Easy Project. To se provádí pomocí takzvaných referenčních klíčových slov. Když je použijete ve zprávě commitu nebo názvu merge requestu v kombinaci s ID úkolu, vytvoří se propojení mezi úkolem a položkou GitLab. Nejběžnější příklady jsou refs #1234 or closes #1234.

Ve většině případů najdete několik přednastavených referenčních klíčových slov. Zde je návod, jak s nimi pracovat.

Přejděte do nabídky Další >> GitLab integrace >> Reference.

Vytvořte nebo upravte referenci
Celý formulář obsahuje popisky, které vám pomohou se v nich orientovat

Nejdůležitější pravidla k zapamatování jsou:

Úkol musí být identifikován ve tvaru #ID , např. #1234
Odpracovaný čas (je-li povolen) se vždy zadává jako @XhYm , např. @1h30m
U commitů je třeba zadat referenční klíčová slova do zprávy commitu
U merge requestů je třeba zadat referenční klíčová slova do názvu merge requestu

3 Mapování uživatelů

Protože se zabýváme integrací dvou různých aplikací, každá má různé skupiny uživatelů. Všechny uživatelské atributy v entitách souvisejících s GitLabem (autor commitu, kontrolor na merge requestu atd.) v Easy Projectu + odpracovaný čas zaznamenaný pomocí referenčních klíčových slov by měly být spojeny se skutečnými uživateli. Jak jsou tedy vlastně uživatelé z GitLabu mapováni na Easy Project?

Nejedná se o nic vědeckého, uživatelé jsou jednoduše mapováni prostřednictvím e-mailu na obou uživatelských profilech. Ujistěte se prosím, že vaši vývojáři mají v GitLabu i Easy Projectu stejné e-maily.

Pokud se některému uživateli z nějakého důvodu nedaří sjednotit e-maily v obou aplikacích, je zde možnost zadat další e-mail v uživatelském profilu Easy Projectu -> zde zadejte e-mail použitý v GitLabu.

4 Jak to funguje

Konečně se dostáváme k oné zábavné části. Co vlastně integrace dělá pro uživatele. Vstupte na hlavní stránku/dashboard GitLab integrace přes nabídku Další (vpravo nahoře) v sekci Přídavné moduly.

Ve výchozím stavu zde najdete přizpůsobitelnou stránku, kterou si později můžete vyladit podle svých potřeb.

Obsahuje také nabídku pro výpis entit nebo vstup do nastavení. Jak již bylo zmíněno v úvodu, Easy Project shromažďuje a zobrazuje 4 klíčové entity z GitLabu. Pojďme se na každou z nich podívat blíže.

4.1 Repozitáře

Seznam repozitářů je funkčně nejméně zajímavý, i když skutečně nezbytný. Za zmínku stojí užitečný filtr s názvem Service, který využijete, pokud máte propojené různé instance GitLabu a potřebujete prohledávat jen některé z nich.

Název repozitáře obsahuje také název jeho skupiny.

Detail repozitáře

Poznámky:

(Od-)Registrovat všechny integrace bylo popsány v kapitole 1.1. Vytvoří/odstraní webhooky v GitLab projektu.
Upravit - ručně změnit některé atributy. Neexistuje žádný jiný důvod než pokročilé ladění pro úpravu jakýchkoli atributů repozitáře v Easy Projectu.
Synchronizovat - stáhne všechna aktuální data z repozitáře.
Merge requesty - vypíše všechny merge requesty v tomto repozitáři.
Vybrat šablonu sekvence - stále ve vývoji, dejte nám prosím více času na vyleštění tohoto robustního nástroje.

4.2 Merge requesty (code requesty)

Měli bychom si ujasnit, proč existují dvě jména. Merge request je termín používaný v GitLabu. Jiné nástroje mají různé názvy, například Pull request. Integrační mechanismus našeho nástroje je napsán obecně, abychom mohli rozšířit podporu na další platformy Git. Proto v aplikaci a obrázcích můžete najít popisek Code request, což je obecný termín, který lze použít pro Merge requesty nebo Pull requesty.

Merge request je bohatá entita (ukládá všechny důležité atributy), která umožňuje vytvářet pěkné výpisy, reporty a grafy nad nimi přímo v Easy Projectu.

Detail merge requestu

Poznámky:

Název merge requestu obsahuje referenční klíčové slovo „refs“ následované ID úkolu s hash #765 – proto byl propojen s úkolem 765
Kliknutím na Synchronizovat se aktualizují všechna data tohoto MR z GitLabu
Všechny atributy lze zobrazit v seznamu merge requestů
Všechny atributy kromě SHA lze použít jako filtry v seznamu/zprávě/grafu merge requestů
Seznam merge requestů obsahuje také atributy testů (CI/CD), které se k němu vztahují, především - Stav testu

4.3 Commity

Podobně jako u merge requestů nabízí seznam commitů také rozsáhlé možnosti reportování. Seznam commitů obsahuje také atributy z testů.

Commit nemá v Easy Projectu vlastní detailní pohled. Jednoduše není potřeba. Kliknutím na URL (nebo SHA) budete přesměrováni na jeho detail v GitLabu.

4.4 Testy

Byly zmíněny ve vztahu k výše uvedeným entitám. Testy mají také svůj vlastní seznam pro generování různých reportů. Pravděpodobně nejběžnějším využitím bude živé zobrazení testů na kritických repozitářích, jako jsou release candidates.

Test také nemá vlastní detailní zobrazení, kliknutím se dostanete do GitLabu.

4.5 Synergie – pohled z úkolu

Pojďme se podívat, jak to všechno jde dohromady.

1 Celkový stav entit GitLabu souvisejících s tímto úkolem. Může obsahovat různé kombinace barev (červená, oranžová, zelená) a ikon (fajfka, křížek). Nejlepší je samozřejmě zelená fajfka v zeleném rámečku
Kombinace závisí na stavu merge requestu(-ů) a výsledcích testů souvisejících s commity a merge requesty. Účelem je na první pohled ukázat, jak probíhá „technický“ průběh tohoto úkolu, což je užitečné zejména pro QA nebo delivery manažery.

2 Název repozitáře(-ů), do kterého byly provedeny změny týkající se tohoto úkolu. Kliknutím na odkaz budete přesměrováni na seznam těchto commitů.

3 Název merge requestů odkazujících na tento úkol. Kliknutím na něj budete přesměrováni na detail MR v Easy Projectu. V případě, že existují pouze commity odkazující na tento úkol, ale chybí merge request, je tato hodnota prázdná.

4 Stav každého merge requestu. Kliknutím na něj budete přesměrováni na detail merge requestu v GitLabu. V případě, že existují pouze commity odkazující na tento úkol, ale merge request chybí, je tato hodnota prázdná.

5 Výsledek posledního spuštěného testu v merge requestu. Kliknutím na něj budete přesměrováni na pipeline v GitLabu. Ve stavu Neznámý na něj nelze kliknout (pipeline neexistuje). V případě, že existují pouze commity odkazující na tento úkol, ale chybí merge request, hodnota ukazuje výsledek posledního testu spuštěného při posledním commitu.

6 Spustit test ručně – kliknutím spustíte pipeline ručně (dostanete se do GitLabu).

7 Kliknutím vytvoříte merge request. Hodí se, když máte pouze sadu commitů, ale chybí vám MR (dostanete se do GitLabu).

4.6 Vytvořit větev z úkolu

(Poznámka: Funkce dostupná od verze 11plus.6.0)

Některým uživatelům se hodí vytvořit větev přímo z úkolu. Tlačítko najdete v menu Další na detailu úkolu.

V poli automatického vyplňování vyberte úložiště. Název větve má předvyplněné ID úkolu a předmět, ale můžete jej změnit. Zdrojová větev je předvyplněna masterem.

Větev uvidíte jako štítek v sekci "Gitlab integrace" na úkolu. Můžete na ni kliknout a dostat se tak na větev v GitLabu.

5 Práva

Aktuálně existují dvě práva:

Zobrazit – přístup k přídavnému modulu z nabídky Další
Spravovat – umožňuje upravovat dashboard

Globální konfigurace je přístupná pouze pro administrátora Easy Projectu.