GitHub integrace

Obsah

0 Úvod
1 Navázání připojení
1.1 Řešení problémů s připojením
2 Práce s klíčovými slovy
3 Mapování uživatelů
4 Jak to funguje
4.1 Repozitáře
4.2 Pull requesty (žádosti o kód)
4.3 Commity
4.4 Testy
4.5 Synergie – pohled z úkolu
5 Oprávnění

 

0 Úvod

Integrace s GitHubem je doplněk, který lze přidat k jakémukoli ze tří plánů Easy Project.

Cílem tohoto doplňku je agregovat důležitá data z GitHubu do Easy Projectu za účelem zlepšení reportování, hodnocení a prezentace vývojových aktivit, a tím podpořit rozhodování zainteresovaných osob ve vývojových projektech a procesech společnosti.

Mezi hlavní funkce patří velmi jednoduché počáteční propojení s vaší instancí GitHubu (jak samostatně hostovanou, tak cloudovou). Po navázání připojení zobrazí Easy Project nejdůležitější položky z GitHubu v konfigurovatelných a filtrovatelných seznamech (podobně jako seznam úkolů). Mezi tyto entity patří:

• Repozitáře
• Pull requesty
• Commity
• Testy

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

Klíčovým prvkem integrace je, že Easy Project NEKOPÍRUJE repozitáře fyzicky. Kód zůstává v GitHubu.

 

1 Navázání připojení

Nejprve potřebujete přístupový token od uživatele v GitHubu s odpovídajícími oprávněními.

1. Vyberte uživatele, prostřednictvím kterého bude Easy Project přistupovat k GitHubu. Může to být speciální uživatel, pod kterým se nikdo nepřihlašuje, například er_integrator
   
2. Přihlaste se do GitHubu tímto uživatelem
3. Klikněte na avatar >> Nastavení
   
   
4. Přejděte do části Vývojářská nastavení
   
   
5. Vyberte Osobní přístupové tokeny
   
   
6. Vygenerujte nový token
   
   
7. Musíte povolit následující oprávnění (scopes):
   - repo (Úplná kontrola nad soukromými repozitáři)
   - admin:repo_hook (Úplná kontrola nad hooky repozitářů)
   - user (Aktualizace VŠECH uživatelských dat)
8. Zkopírujte token
   
   Nyní můžete přejít do Easy Project a zadat potřebné údaje.
   
   
9. Přejděte do Admin >> Git integrace >> Najděte Dostupné integrace a klikněte na Přidat
   
   
10. Pojmenujte své připojení, zadejte URL a vložte přístupový token, který jste vygenerovali.
    Poznámka: V případě cloudu, například https://github.com/robogithub-easy, zadejte pouze https://github.com/ bez další cesty. Nemusíte se obávat, uvidíte pouze projekty, ke kterým má uživatel s přístupovým tokenem oprávnění. Pokud máte všechny projekty nastaveny jako soukromé, nikdo jiný je neuvidí.
    
    
11. Uložte
12. A to je vše! Připojení je hotové.

Všechno ostatní se provádí automaticky na pozadí. Konkrétně:

• Easy Project načte všechny projekty/repzitáře, jejichž členem je uživatel s přístupovým tokenem.
  
• V těchto repozitářích se vytvoří webhooky => aby se informace o nových commitech, pull requestech a testech odesílaly do Easy Project.

 

1.1 Řešení problémů s připojením

Problém A
Nevidím žádný repozitář z této instance GitHubu
Vzhledem k nepředvídatelným okolnostem se může stát, že operace výše neprobíhnou úspěšně. V důsledku toho nemusíte vidět žádný repozitář z této instance GitHubu v aplikaci Easy Project.

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

1. Jděte do Admin >> Git integrace >> Konfigurované integrace >> Klikněte na název
   
   
2. V bočním menu klikněte na Přidat repozitář
   
   
3. Najděte repozitář
   [image]knowledge-base/github/find-repo.png[/image]]
   
4. Po výběru se ostatní pole automaticky vyplní
   
5. Klikněte na Uložit
   Repozitář je přidán
   
   
   

Problém B
Repozitáře byly nalezeny, ale moje nové committy, pull requesty a testy nejsou přidány do Easy Projectu
Nová data z GitHubu jsou odesílána do Easy Projectu prostřednictvím webhooků nastavených v GitHubu. Za normálních okolností jsou vytvářeny automaticky. Můžete to ověřit ve vašem projektu GitHub >> Nastavení >> Webhooky

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

1. Jděte do Admin >> Git integrace >> Konfigurované integrace >> Klikněte na název
   
   
2. V bočním menu klikněte na Repozitáře
   
   
3. Klikněte na název jednoho
   
   
4. Klikněte na Registrovat všechny integrace
   
   

Tímto se ručně vygeneruje webhook ve správném formátu.

Pokud webhook existuje, ale obsahuje indikaci chyby, zkontrolujte chybovou zprávu a pokuste se chybu vyřešit podle ní.

 

2 Referenční klíčová slova

Teď, když je základní připojení nakonfigurováno, již máte informace z GitHubu v aplikaci Easy Project a můžete je využívat. Abychom ale využili integraci naplno, je potřeba provést ještě několik dalších nastavení. Některá z nich jsou již přednastavena a vy je můžete pouze zkontrolovat.

Je možné propojit konkrétní commity nebo pull requesty s konkrétními úkoly a dokonce logovat čas tímto způsobem, aniž byste museli navštěvovat Easy Project. Toho je dosaženo pomocí takzvaných referenčních klíčových slov. Když je použijete v popisu commitu nebo názvu pull requestu ve spojení s ID úkolu, vytvoří to odkaz mezi úkolem a položkou na GitHubu. Nejčastější příklady jsou refs #1234 nebo closes #1234

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

1. Jděte do globálního menu >> Git integrace >> Reference
   
2. Vytvořte nebo upravte referenci
3. Celý formulář obsahuje nápovědy, které vám pomohou orientovat se při jejich vyplňování
   
   

Nejdůležitější pravidla, která je třeba si zapamatovat, jsou:

• Úkol musí být označen ve formátu #ID, např. #1234
• Logování času (pokud je povoleno) se vždy zadává ve formátu @XhYm, např. @1h30m
  
• U commitů musí být referenční klíčová slova zadána v popisu commitu
• U pull requestů musí být referenční klíčová slova zadána v názvu pull requestu

 

3 Mapování uživatelů

Jelikož se jedná o integraci dvou různých aplikací, každá z nich má jiný soubor uživatelů. Všechny uživatelské atributy na entitách souvisejících s GitHubem (autor commitu, recenzent na pull requestu, atd.) v Easy Projectu a čas strávený pomocí referenčních klíčových slov by měly být spojeny s reálnými uživateli. Jak tedy uživatelé z GitHubu mapují do Easy Projectu?

Nic vědeckého, uživatelé jsou jednoduše mapováni přes e-mail v obou uživatelských profilech. Ujistěte se, že vaši vývojáři mají identické e-maily v GitHubu i v Easy Projectu.

Pokud z nějakého důvodu jeden uživatel nemůže sjednotit e-maily v obou aplikacích, existuje možnost zadat další e-mail v Easy Projectu v uživatelském profilu -> zadejte zde e-mail GitHubu.

 

4 Jak to funguje

Nakonec se dostáváme k té zábavné části. Co integrace vlastně dělá pro uživatele. Přístup k Dashboardu Git integrace naleznete v globálním menu (vpravo nahoře) v sekci Add-ons.

Najdete Dashboard v základním stavu, kterou si později můžete upravit podle svých potřeb.

Obsahuje také menu pro zobrazení entit nebo zadání nastavení. Jak bylo zmíněno v úvodu, Easy Project shromažďuje a zobrazuje 4 klíčové entity z GitHubu. Pojďme se podívat na každou z nich.

4.1 Repozitáře

Seznam repozitářů je funkčně nejméně zajímavý, i když skutečně nezbytný. Užitečný filtr, který stojí za zmínku, se nazývá Service, který použijete, pokud máte připojené různé instance GitHubu a potřebujete prohledávat pouze některé z nich.

Detail repozitáře

Poznámky:

• (De-)Registrovat všechny integrace bylo popsáno v kapitole 1.1. Vytvoří/smaže webhooks v projektu GitHubu.
• Upravit - ručně změnit některé atributy. Neexistuje žádný důvod k úpravě atributů repozitáře v Easy Projectu kromě pokročilé ladění.
  
• Synchronizovat - stáhne všechna aktuální data z repozitáře.
• Pull requesty - zobrazí všechny pull requesty v tomto repozitáři.
• Vybrat šablonu sekvence - stále ve vývoji, dejte nám více času na doladění tohoto robustního nástroje.

4.2 Pull requesty (Code requests)

Je třeba objasnit, proč existují dvě názvy. Pull request je termín používaný v GitHubu. Jiná nástroje mají pro tento termín různé názvy, například Merge request. Integrační mechanismus našeho nástroje je napsán obecně, abychom mohli rozšířit podporu na jiné Git platformy. Proto v aplikaci a obrázcích můžete najít označení Code request, což je obecný termín, který se může vztahovat jak na Pull requesty, tak na Merge requesty.

Pull request je bohatá entita (uchovává všechny důležité atributy), která umožňuje vytvářet hezké seznamy, reporty a dokonce grafy nad nimi přímo v Easy Projectu.

Detail pull requestu

Poznámky:

• Název pull requestu obsahuje referenční klíčové slovo "refs" následované ID úkolu s hashem #765 – proto byl propojen s úkolem 765
• Kliknutím na Synchronizovat se aktualizují všechna data tohoto PR z GitHubu
• Všechny atributy mohou být zobrazeny v seznamu pull requestů
• Všechny atributy kromě SHA mohou být použity jako filtry v seznamu/reportu/grafu pull requestů
• Seznam pull requestů také obsahuje atributy testů (CI/CD) související s ním, nejdůležitější je - Stav testu

 

4.3 Commity

Podobně jako u pull requestů, seznam commitů také poskytuje široké možnosti reportování. Seznam commitů také obsahuje atributy z testů.

Commit nemá svůj vlastní detailní pohled v Easy Projectu. Prostě pro něj není potřeba. Kliknutím na URL (nebo SHA) budete přesměrováni na detail v GitHubu.

 

4.4 Testy

Byly zmíněny v souvislosti s výše uvedenými entitami. Testy mají také svůj vlastní seznam pro generování různých reportů. Pravděpodobně nejběžnější použití bude živý přehled testů na kritických repozitářích, jako jsou release kandidáty.

Testy také nemají svůj vlastní detailní pohled, kliknutím budete přesměrováni na GitHub.

 

4.5 Synergie - pohled z úkolu

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

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

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

3 Název pull requestu(ů) týkajícího se tohoto úkolu. Kliknutím na něj budete přesměrováni na detail PR v Easy Projectu.
Pokud existují pouze commity týkající se tohoto úkolu, ale chybí pull request, tato hodnota bude prázdná.

4 Stav každého pull requestu. Kliknutím na něj budete přesměrováni na detail pull requestu v GitHubu.
Pokud existují pouze commity týkající se tohoto úkolu, ale chybí pull request, tato hodnota bude prázdná.

5 Výsledek posledního spuštěného testu v pull requestu. Kliknutím na něj budete přesměrováni na GitHub. Není klikatelné, pokud je stav Unknown (test neexistuje).
Pokud existují pouze commity týkající se tohoto úkolu, ale chybí pull request, hodnota zobrazuje poslední výsledek testu spuštěného na posledním commitu.

6 Spustit test ručně - přesměruje vás na GitHub.

7 Klikněte pro vytvoření pull requestu. Užitečné, když máte pouze sadu commitů, ale chybí PR (přesměruje vás na GitHub).

 

5 Oprávnění

V současnosti existují dvě oprávnění.

• Zobrazit - Přístup k Add-onu z globálního menu
  
• Spravovat - editace dashboardu
  

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