Ako nastaviť GitLab Continuous Integration (CI) pipelines na Ubuntu 20.04

Každý vývojár chápe, aký kľúčový je systém správy verzií pre životný cyklus vývoja softvéru. Umožňuje viacerým ľuďom pracovať súčasne na jednom projekte, pričom každý človek si udržiava vlastnú kópiu kódu a sám sa rozhoduje, kedy ju bude zdieľať so zvyškom tímu. Na dosiahnutie tohto cieľa vývojári využívajú Git repozitáre, ktoré pomáhajú so správou verzií. GitLab je webový Git repozitár, ktorý je viac než len nástroj na správu verzií. Poskytuje tiež DevOps nástroje, sledovanie problémov (issue-tracking), kontinuálnu integráciu a nasadenie.

GitLab ponúka tri možnosti, z ktorých si môžete vybrať: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) a GitLab SaaS. GitLab CE a GitLab EE sú samo-spravované riešenia. To znamená, že si inštanciu GitLab sami stiahnete, nainštalujete a spravujete. GitLab SaaS je hostovaný spoločnosťou GitLab Inc. Nemusíte sa teda starať o inštaláciu ničoho, aby ste ho mohli používať. Stačí vám len vytvoriť si účet GitLab a začať.

V tomto návode vám ukážeme, ako nastaviť pipeline-y pre kontinuálnu integráciu (Continuous Integration) pomocou GitLab CI na monitorovanie zmien vo vašich repozitároch a spúšťanie automatizovaných testov na overenie nového kódu. Začneme nastavením Git repozitára na hosťovanie kódu. Potom nakonfigurujeme CI proces na monitorovanie commitov do repozitára a spustíme CI runner na vykonanie testov v izolovanom Docker kontajneri.

Požiadavky

Na začiatok budete potrebovať server, na ktorom beží softvér na správu verzií GitLab. Ako samo-spravovaný GitLab, tak aj GitLab SaaS dokážu spúšťať automatizované testy. V bezplatných verziách SaaS však existujú určité obmedzenia týkajúce sa minút a zdrojov, ktoré sú k dispozícii pre vaše testy. Ak používate samo-spravované možnosti, máte väčšiu slobodu, pretože svojej inštancii GitLab môžete prideliť toľko zdrojov, koľko chcete. Postupujte podľa nášho návodu na hosťovanie vlastných Git repozitárov pomocou GitLab, kde sa dozviete, ako si nastaviť vlastnú inštanciu GitLab.

Budete potrebovať aspoň jeden server, ktorý bude slúžiť ako GitLab CI runner. Ak však chcete, môžete mať aj viac serverov. Ak máte nastavenú samo-spravovanú inštanciu GitLab, môžete použiť rovnaký server, ale my uprednostňujeme nastavenie iného servera pre CI runner. Tento návod na Ako nastaviť váš Ubuntu server je dobrým začiatkom.

Na serveroch s GitLab CI runnerom budete potrebovať nainštalovaný Docker, aby ste izolovali testovacie prostredia v Docker kontajneroch. Máme návod na Ako nainštalovať a prevádzkovať Docker na Ubuntu, ktorý vám pomôže splniť túto požiadavku.

Teraz, keď máme všetko, čo potrebujeme, poďme začať!

Krok 1: Vytvorenie projektu na inštancii GitLab

Začneme vytvorením repozitára projektu na GitLabe. Tento návod založíme na Node.js aplikácii. Keďže nechceme vytvárať súbory projektu od nuly, GitLab ponúka nástroj na importovanie projektov z iných repozitárov na správu verzií, ktorý využijeme. Aplikácia, ktorú importujeme, je jednoduchá „hello world“ aplikácia postavená na Express.js – minimalistickom webovom frameworku pre Node.js aplikácie. Testy budeme implementovať pomocou Mocha a Chai – ide o JavaScriptové frameworky používané na unit testovanie. Mocha umožňuje asynchrónne testovanie, reporty o pokrytí testami a môže byť spárovaná s inými assertion knižnicami. Chai je assertion knižnica. Môže byť spárovaná s akýmkoľvek testovacím frameworkom, v našom prípade spárujeme Mocha s Chai.

Teraz, keď poznáte základy nášho projektu, prihláste sa do svojej inštancie GitLab (či už samo-spravovanej alebo SaaS), kliknite na ikonu „plus“ na hornom navigačnom paneli a vyberte „Nový projekt“. Prípadne, ak prejdete na začiatok domovskej stránky vášho účtu, môžete kliknúť na tlačidlo „Nový projekt“:

Na stránke nového projektu kliknite na záložku Importovať projekt:

Potom na otvorenej stránke kliknite na tlačidlo Repo by URL:

Hoci existuje možnosť importu z GitHubu, nebudeme ju používať, pretože vyžaduje osobný prístupový token. Nemusíme nastavovať osobné prístupové tokeny, keďže pracujeme s verejným repozitárom, a importovanie iba pomocou URL adresy je jednoduché.

Potom skopírujte nasledujúcu URL adresu a vložte ju do poľa Git Repository URL:

Malo by to vyzerať takto:

Ponechajte repozitár ako Private a kliknite na tlačidlo Create project po dokončení. Počkajte niekoľko sekúnd, kým sa projekt importuje z GitHubu, a zobrazí sa medzi vašimi GitLab repozitármi. GitLab importuje projekt s rovnakými podrobnosťami ako projekt repozitára GitHub.

Krok 2: Analýza súboru .gitlab-ci.yml

GitLab CI prehľadáva každý repozitár na GitLabe a hľadá súbor s názvom .gitlab-ci.yml , aby vedel, ako má spúšťať automatizované testy. V repozitári, ktorý sme práve importovali, môžete vidieť súbor .gitlab-ci.yml medzi súbormi projektu. Viac informácií o GitLab CI yml nájdete v ich oficiálnej Referencii kľúčových slov pre dokumentáciu súboru .gitlab-ci.yml.

Keď ste v rozhraní repozitára GitLab, kliknite na súbor .gitlab-ci.yml , aby ste ho otvorili v prehliadači. Malo by to vyzerať takto:

Všimnite si odsadenie riadkov. Súbor sa riadi prísnou GitLab CI YAML syntaxou konfigurácie , aby definoval rôzne akcie, ktoré sa majú vykonať, v určenom poradí za určitých podmienok. Na zabezpečenie správnosti vašich konfiguračných súborov poskytuje GitLab testovací nástroj na validáciu. Vo vašej inštancii GitLab, vo vašom projektovom repozitári, môžete navštíviť rozhranie CI lint na validáciu vášho .gitlab-ci.yml. Kliknite na CI/CD v ľavom navigačnom menu a kliknite na tlačidlo CI lint na stránke, ktorá sa zobrazí:

Direktívy v konfiguračnom súbore sú popísané nižšie.

• Základný Docker obraz

Prvý riadok v konfiguračnom súbore deklaruje Docker obraz, ktorý by sa mal použiť na spustenie testov. Keďže vytvárame aplikáciu Node.js, použijeme najnovší obraz Node.js:

• Stages

Potom definujeme rôzne fázy, ktorými chceme, aby naše testy kontinuálnej integrácie prešli. Máme iba dve fázy:

Pri definovaní názvov fáz sú názvy ako build alebo test zvolené náhodne – môžete si vybrať akýkoľvek názov. Fázy však musíte správne usporiadať, pretože to určuje tok vykonávania. V našom prípade sa úlohy vo fáze build vykonajú pred úlohami vo fáze test . GitLab runner vykoná úlohy v rovnakej fáze paralelne a pred spustením úloh v ďalšej fáze počká na dokončenie všetkých úloh.

• Cache

Definícia cache je zahrnutá na určenie súborov a adresárov, ktoré sa uložia do cache alebo sa uložia na neskoršie použitie medzi spusteniami úloh:

Definovanie ukladania do cache pomáha minimalizovať čas potrebný na spustenie úloh, ktoré závisia od zdrojov, pri ktorých je nepravdepodobné, že sa medzi spusteniami zmenia. Špecifikujeme adresár node_modules , ktorý sa má uložiť do cache. Toto je adresár, do ktorého npm inštaluje závislosti pre projekt.

• Jobs

V konfigurácii máme dve úlohy:

• install_dependencies

Pri pomenovávaní úloh si môžete vybrať akýkoľvek názov. Odporúča sa však použiť popisný názov, keďže sa používajú v používateľskom rozhraní GitLabu – to môže byť užitočné pri ladení. Na webe nájdete väčšinu konfigurácií, ktoré kombinujú npm install s príkazmi v testovacej fáze. Oddelili sme ich len preto, aby sme pomohli demonštrovať, ako úlohy navzájom interagujú, keďže ide o pomerne malý projekt. stage direktíva označuje túto úlohu ako build – spúšťa sa v build stage.

Direktíva script špecifikuje príkazy, ktoré sa majú spustiť pri vykonávaní tejto úlohy. Viacero príkazov môžete špecifikovať pridaním riadkov do bloku script . Samozrejme, musíte si dať pozor na správne odsadenie a mať na pamäti poradie, v akom by sa mali skripty vykonávať.

Direktíva artifacts špecifikuje súbory alebo cesty k adresárom, ktoré sa majú uložiť a zdieľať medzi fázami. Opäť pripomíname, že správne usporiadanie fáz je kľúčové pre zabezpečenie toho, aby ostatné súbory mali to, čo potrebujú na vykonanie. Príkaz npm install nainštaluje závislosti do adresára node_modules . Deklarovaním v artifacts ho sprístupníme pre úlohy vykonávané v nasledujúcich fázach. Súbory sú k dispozícii aj v rozhraní GitLab UI, ak by ste si ich chceli stiahnuť.

• test_with_mocha

Táto úloha sa spúšťa vo fáze test . Keďže táto úloha beží po spustení úlohy vo fáze build , artefakty deklarované vo fáze build (čo sú závislosti pre našu aplikáciu) budú k dispozícii pre fázu test . Blok script špecifikuje príkazy npm na spustenie našich testov. Najprv spustíme našu aplikáciu a potom spustíme testy voči aplikácii. Spustenie týchto príkazov aktivuje príkazy špecifikované v sekcii bloku skriptov v package.json :
Týmto by ste mali mať základné znalosti o súbore .gitlab-ci.yml . Hovoríme základné, pretože toto je len statická aplikácia hello world . Ďalej sa pozrime na to, ako môžeme spustiť nový beh CI.

Krok 3: Spustenie behu GitLab CI

Určite vás poteší, že akonáhle má váš repozitár súbor .gitlab-ci.yml , akékoľvek nové commity, ktoré doň pushnete, spustia nový beh Continuous Integration. V prípade self-managed inštancií GitLab, ak nemáte nakonfigurovaný GitLab runner, beh CI bude nastavený na „pending“ (čakajúci).

GitLab SaaS poskytuje používateľom zdieľané runnery (shared runners), ktoré môžu prevziať ich úlohy a automaticky ich vykonať. To je možné len vtedy, ak sú zdieľané runnery voľné a neprekročili ste svoju kvótu. V GitLab SaaS si môžete vybrať, či chcete, aby váš repozitár používal zdieľané runnery alebo nie, prechodom na stránku vášho projektu Settings > CI / CD , ako je znázornené na snímke obrazovky nižšie. Na tejto stránke nájdete aj informácie o pokynoch na inštaláciu GitLab runnera, ktorým sa budeme podrobnejšie venovať v ďalšom kroku:

Teraz urobme malú zmenu, aby sme spustili beh CI. Prejdite späť do repozitára vášho GitLab projektu node_pipeline :

Kliknite na súbor README.md zvýraznený vyššie, aby ste si ho mohli prezrieť:

Kliknutím na tlačidlo ‘Edit’ otvoríte súbor na úpravu v prehliadači a pridajte nejaký text:

Po pridaní textu prejdite nadol a kliknutím na tlačidlo Commit changes uložte zmeny. Správu o commite môžete upraviť podľa vlastného uváženia. Počas behu pipeline sa zobrazí ako názov v rozhraní GitLab UI. Nechali sme ju ako Update README.md , keďže je to celkom popisné:

Po odoslaní zmien (commitnutí) sa vráťte na hlavnú stránku projektu. Všimnete si malú ikonu pozastavenia priradenú k najnovšiemu commitu. Ak nad ikonu prejdete myšou, zobrazí sa: ‘Pipeline:pending’:

To znamená, že beh CI bol spustený. Testy sa však ešte nespustili. V navigačnom menu vľavo kliknite na CI/CD, a potom vyberte Pipelines. Tým sa otvorí stránka s podrobnejšími informáciami o pipeline. Môžete vidieť, že CI čaká (pending) a je označená ako zaseknutá (stuck):

Ak chcete získať viac podrobností o behu, kliknite na stav pending . Uvidíte zobrazenie nižšie, ktoré ukazuje rôzne fázy behu a jednotlivé úlohy prepojené s každou fázou:

Môžete tiež kliknúť na jednotlivé úlohy a zobraziť ich podrobnosti, napríklad čo spôsobuje oneskorenie. V prípade neúspešných spustení tu uvidíte, čo spôsobilo zlyhanie úlohy:

Správa indikuje, že úloha uviazla, pretože ste nenakonfigurovali žiadne aktívne runnery, ktoré by ju mohli vykonať. Urobíme to v nasledujúcom kroku. Keď sprístupníte runner, úloha sa začne vykonávať automaticky. Keď sa úloha vykoná, uvidíte výstup v tomto rozhraní, ako aj ďalšie stiahnuteľné artefakty vygenerované počas behu úlohy.

Krok 4: Nastavenie služby GitLab CI Runner

Teraz je čas využiť druhý server, ktorý sme deklarovali v časti Požiadavky tohto návodu. Na tomto serveri nainštalujeme a nastavíme službu GitLab runner. Službu môžete nasadiť tak, aby spúšťala viacero inštancií runnerov pre rôzne projekty na GitLabe.

Máte možnosť nasadiť runner na rovnakom serveri, ktorý hostí vašu vlastnú (self-managed) inštanciu GitLabu. Aby sa však zabezpečilo, že inštancia nebude obmedzená prostriedkami, je lepšie nastaviť samostatnú inštanciu CI runnera. Bez ohľadu na to, ktorú konfiguráciu si vyberiete, musí byť nainštalovaný Docker na izoláciu testovacích prostredí.

Proces inštalácie GitLab CI runnera je porovnateľný s procesom pre inštaláciu vlastnej (self-managed) inštancie GitLabu . Začneme stiahnutím skriptu na pridanie oficiálneho repozitára GitLab do zdrojov apt pomocou nasledujúceho príkazu:

Po zobrazení výzvy zadajte svoje heslo root. Ďalej môžete spustiť príkaz na inštaláciu najnovšieho GitLab CI runnera:

Vyššie uvedený príkaz nainštaluje a zaregistruje službu runnera pripravenú na použitie vo vašich projektoch.

Krok 5: Získanie registračných tokenov a prepojenie GitLab Runnera

Na nastavenie GitLab CI runnera, aby začal prijímať úlohy, potrebujete token runnera GitLab. Je potrebný na to, aby sa runner autentifikoval vo vašej inštancii servera GitLab. Existujú dva typy tokenov v závislosti od toho, ako chcete runner používať: špecifický pre projekt a zdieľaný runner.

Runnery špecifické pre projekt sú použiteľné, ak máte na runner jedinečné požiadavky. Napríklad, ak máte definície nasadenia vo vašom súbore gitlab-ci.yml s jedinečnými tokenmi, potom sa môže odporúčať špecifický runner na správnu autentifikáciu v prostredí nasadenia. Ďalším faktorom je, ak vaše fázy kontinuálnej integrácie obsahujú procesy náročné na zdroje. Vtedy by bolo ideálne použiť runner špecifický pre projekt. Upozorňujeme, že runner špecifický pre projekt neprijíma úlohy z iných projektov.

Zdieľané runnery sú univerzálne a môže ich používať viacero projektov. Inštancia GitLab SaaS hostovaná na GitLab Inc má niekoľko zdieľaných runnerov, ktoré automaticky prevezmú vaše pipeline, ako je vysvetlené v treťom kroku. Runnery preberajú úlohy z vašich konfigurácií na základe algoritmu, ktorý zohľadňuje počet úloh aktuálne vykonávaných pre každý projekt. Zdieľaný runner je flexibilnejší ako špecifický runner. Dá sa nakonfigurovať z administrátorského účtu inštancie GitLabu. Pozrime sa, ako môžeme získať tokeny pre oba runnery.

• Registrácia runnera špecifického pre projekt

Ak chcete zaregistrovať runner špecifický pre projekt, otvorte svoj projekt vo vašej inštancii GitLabu alebo v účte GitLab SaaS. V navigačnom menu vľavo kliknite na položku Settings a vyberte možnosť CI/CD možnosť:

Potom prejdite nadol na sekciu Runners a kliknutím na tlačidlo sekciu rozbaľte:

Ľavá strana vysvetľuje, ako zaregistrovať runner špecifický pre projekt. Toto je zobrazenie inštancie GitLab SaaS. Môžete tiež nakonfigurovať automatické runnery pomocou Kubernetes, ale v tomto návode nastavujeme manuálny runner:

Ďalej sa musíte zamerať na sekciu, kde dostanete token pre tento projekt. Pre self-managed inštanciu GitLabu bude URL zobrazovať doménu servera, na ktorom vaša inštancia GitLabu beží:

Zdieľané runnery pre tento projekt môžete zakázať prepnutím prepínača v pravej časti pod Shared Runners. Potom skopírujte zobrazený registračný token do poznámkového bloku, pretože ho použijeme neskôr.

• Registrácia zdieľaného runnera

Ak chcete zaregistrovať zdieľaný runner, musíte sa prihlásiť do svojej self-managed inštancie GitLabu ako administrátor. Pre prístup do administračného panelu kliknite na ikonu kľúča v hornom navigačnom menu:

V Admin Panel, kliknite na Runners v sekcii Overview v ľavom menu. Tým sa otvorí stránka s pokynmi na konfiguráciu Shared Runners:

Skopírujte registračný token zobrazený na pravej strane pod Set up a shared Runner manually. Tento token použijete na registráciu runnera v ďalšom kroku.

• Prepojenie GitLab CI Runnera s inštanciou GitLabu

V tomto kroku prepojíte svoju inštanciu GitLabu s CI runnerom. Prihláste sa späť na server, kde ste nainštalovali službu GitLab runner v štvrtom kroku. Ak chcete spustiť proces registrácie runnera, zadajte do terminálu nasledujúci príkaz:

Príkaz vás vyzve na sériu otázok:

• Zadajte URL inštancie GitLabu (napríklad https://gitlab.com/):

Zadajte doménový názov vašej inštancie GitLabu pomocou https:// na špecifikáciu SSL.

• Zadajte registračný token:

Zadajte svoj registračný token. Tu si vyberiete, či chcete, aby bol tento runner špecifický pre projekt alebo zdieľaný. Pre ktorúkoľvek z možností môžete zadať iba jeden z tokenov, ktoré ste si predtým skopírovali.

• Zadajte popis pre runner:

Vyberte popisný názov pre váš CI runner, pod ktorým sa bude zobrazovať v rozhraní inštancie GitLabu.

• Zadajte executor: custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Tu máte možnosť vybrať si executor na spúšťanie úloh. Zadajte Docker.

• Zadajte tagy pre runner (oddelené čiarkou):

Toto je voliteľné. Môžete zadať akékoľvek názvy tagov, napríklad závislosti, ktoré tento runner obsahuje. Zatiaľ to môžete nechať prázdne.

• Zadajte predvolený Docker obraz (napríklad ruby:2.6):

Tu sa očakáva, že špecifikujete predvolený univerzálny obraz používaný na spúšťanie úloh v prípade, že súbor gitlab-ci.yml nešpecifikuje obraz. Zadajte alpine:latest keďže ide o malý, univerzálny a bezpečný obraz. Stlačte enter a runner sa automaticky zaregistruje a spustí:

Ak chcete zobraziť zoznam aktuálne dostupných runnerov, zadajte nasledujúci príkaz:

Krok 6: Potvrdenie úspešného prepojenia CI Runnera v GitLabe

Ďalej sa vráťte do prehliadača a navštívte stránku svojho projektu v inštancii GitLabu. V závislosti od toho, koľko minút uplynulo od registrácie runnera, môžete vidieť, že úloha práve beží:

Alebo už mohla byť dokončená:

Potom prejdite na stránku Pipelines buď cez ľavé menu CI/CD > Pipelines, alebo kliknutím na ikonu running, passed, alebo failed (ak pipeline narazil na chyby), aby ste videli stav spustenia CI. Tu vidíme, že jedna z fáz (build stage) úspešne prebehla, zatiaľ čo jedna stále beží:

V tabuľke pod hlavičkou Stages kliknite na jednu z ikon fáz, aby ste zobrazili priradené úlohy:

Potom kliknite na úlohu vo vyskakovacom okne, aby ste zobrazili podrobnosti:

Úloha prebehla a môžete vidieť priebeh, keď príkaz npm inštaloval závislosti. Na pravej strane si môžete pozrieť ďalšie súvisiace informácie. Máte možnosť stiahnuť si artefakty z úlohy. V rozbaľovacej ponuke môžete tiež prepínať medzi fázami a zobraziť iné úlohy.

Tu si môžete pozrieť naše testovacie prípady, ktoré sa zobrazia, keď vyberiete úlohu vo fáze testovania (test stage):

Available Runners

V ľavom menu, ak kliknete na Settings > CI/CD, a rozbalíte sekciu Runners sekcii by ste mali vidieť runnera, ktorého ste práve zaregistrovali. V závislosti od toho, či ste špecifikovali token pre konkrétny projekt alebo zdieľaný token, sa runner zobrazí v príslušnej sekcii.

Tu môžete vidieť, že sme zaregistrovali token špecifický pre projekt. Runner sa zobrazuje pod Specific Runners:

Záver

V tomto návode ste sa naučili, ako môžete automatizovať svoje testy pomocou GitLab CI. Začali sme nastavením projektu aplikácie Node.js na GitLab-e. Projekt obsahoval niekoľko testovacích prípadov a gitlab-ci.yml. Dozvedeli sme sa, že GitLab používa gitlab-ci.yml súbor na určenie toho, čo má robiť, keď sa spustí. Súbor gitlab-ci.yml je len konfiguračný súbor, ktorý obsahuje inštrukcie na zostavenie a testovanie aplikácií, napísaný v YAML formáte, ktorému dokáže porozumieť GitLab CI runner.

Podarilo sa nám tiež nastaviť GitLab CI runner na samostatnom hostiteľovi. Zaregistrovali sme ho, aby preberal úlohy z našich inštancií GitLab-u vždy, keď dôjde k spusteniu. Hoci išlo o jednoduchý projekt, na základe týchto informácií môžete nastaviť pipeline pre zložité projekty. Kroky na pridanie projektu do GitLab-u a prepojenie GitLab CI runnera zostávajú rovnaké. To, čo sa mení, sú inštrukcie a fázy v gitlab-ci.yml súbore.

Príjemnú prácu!