Jak nastavit GitLab Continuous Integration (CI) pipelines na Ubuntu 20.04

Každý vývojář chápe, jak zásadní je správa verzí pro životní cyklus vývoje softwaru. Umožňuje více lidem pracovat současně na jednom projektu, přičemž každý si udržuje vlastní kopii kódu a sám se rozhoduje, kdy ji bude sdílet se zbytkem týmu. K dosažení tohoto cíle vývojáři využívají Git repozitáře, které jim se správou verzí pomáhají. GitLab je webový Git repozitář, který je víc než jen nástroj pro správu verzí. Dále poskytuje DevOps nástroje, sledování problémů (issue-tracking), průběžnou integraci a nasazení.

GitLab nabízí tři možnosti, ze kterých si můžete vybrat: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) a GitLab SaaS. GitLab CE and GitLab EE jsou samoobslužná řešení (self-managed). To znamená, že si instanci GitLab sami stáhnete, nainstalujete a spravujete. GitLab SaaS je hostován společností GitLab Inc. Nemusíte se tedy starat o instalaci čehokoli, abyste jej mohli používat. Stačí pouze vytvořit účet GitLab a začít.

V tomto návodu vám ukážeme, jak nastavit pipeline pro průběžnou integraci (Continuous Integration) pomocí GitLab CI pro sledování změn ve vašich repozitářích a spouštění automatických testů k ověření nového kódu. Začneme nastavením Git repozitáře pro hostování kódu. Poté nakonfigurujeme CI proces pro sledování commitů do repozitáře a spustíme CI runner pro spuštění testů v izolovaném Docker kontejneru.

Požadavky

Pro začátek budete potřebovat server, na kterém běží software pro správu verzí GitLab. Jak samoobslužný GitLab (self-managed), tak SaaS verze umožňují spouštět automatické testy. V bezplatných možnostech SaaS však existují určitá omezení, pokud jde o minuty a prostředky, které jsou pro vaše testy k dispozici. Pokud používáte samoobslužné možnosti, máte větší svobodu, protože své instanci GitLab můžete přidělit tolik prostředků, kolik chcete. Postupujte podle našeho návodu na hostování vlastních Git repozitářů pomocí GitLabu , abyste se dozvěděli, jak nastavit vlastní instanci GitLab.

Budete potřebovat alespoň jeden server, který bude sloužit jako GitLab CI runner. Pokud však chcete, můžete mít i více serverů. Pokud jste si nastavili samoobslužnou instanci GitLab, můžete použít stejný server, ale pro CI runner dáváme přednost nastavení jiného serveru. Tento návod na Jak nastavit server Ubuntu je dobrým začátkem.

Na serverech s GitLab CI runnerem budete potřebovat nainstalovaný Docker, abyste izolovali testovací prostředí v Docker kontejnerech. Máme návod na Jak nainstalovat a provozovat Docker na Ubuntu , který vám pomůže tento požadavek splnit.

Nyní, když máme vše potřebné, můžeme začít!

Krok 1: Vytvoření projektu na instanci GitLab

Začneme vytvořením repozitáře projektu na GitLabu. Tento návod založíme na aplikaci v Node.js. Protože nechceme vytvářet soubory projektu od nuly, GitLab nabízí nástroj pro import projektů z jiných repozitářů pro správu verzí, který využijeme. Aplikace, kterou importujeme, je jednoduchá „hello world“ aplikace postavená na Express.js – a minimalist web framework for Node.js applications. Testy budeme implementovat pomocí Mocha a Chai – což jsou JavaScriptové frameworky používané pro unit testování. Mocha umožňuje asynchronní testování, reporty o pokrytí testů a lze ji spárovat s jinými knihovnami pro aserce (assertion libraries). Chai je aserční knihovna. Lze ji spárovat s jakýmkoli testovacím frameworkem, v našem případě spárujeme Mocha s Chai.

Nyní, když znáte základy našeho projektu, přihlaste se ke své instanci GitLab (ať už samoobslužné nebo SaaS), klikněte na ikonu „plus“ na horním navigačním panelu a vyberte „Nový projekt“. Volitelně, pokud přejdete na začátek domovské stránky svého účtu, můžete kliknout na tlačítko „Nový projekt“:

Na stránce nového projektu klikněte na záložku Importovat projekt:

Dále na otevřené stránce klikněte na tlačítko Repo by URL:

I když je k dispozici možnost importu z GitHubu, nebudeme ji používat, protože vyžaduje osobní přístupový token (Personal access token). Osobní přístupové tokeny nemusíme nastavovat, protože pracujeme s veřejným repozitářem, a import pouze pomocí URL je přímočarý.

Poté zkopírujte následující URL a vložte ji do pole Git Repository URL:

Mělo by to vypadat takto:

Ponechte repozitář jako Private a klikněte na tlačítko Create project po dokončení. Počkejte několik sekund, než se projekt importuje z GitHubu, a poté se objeví mezi vašimi repozitáři na GitLabu. GitLab importuje projekt se stejnými podrobnostmi jako projekt repozitáře na GitHubu.

Krok 2: Analýza souboru .gitlab-ci.yml

GitLab CI prohledává každý repozitář na GitLabu a hledá soubor s názvem .gitlab-ci.yml, aby věděl, jak má spouštět automatizované testy. V repozitáři, který jsme právě importovali, můžete vidět soubor .gitlab-ci.yml mezi soubory projektu. Více informací o GitLab CI yml naleznete v jejich oficiální dokumentaci Keyword reference for the .gitlab-ci.yml file.

V rozhraní repozitáře GitLab klikněte na soubor .gitlab-ci.yml, abyste jej otevřeli v prohlížeči. Mělo by to vypadat takto:

Všimněte si odsazení řádků. Soubor se řídí přísnou GitLab CI YAML konfigurační syntaxí pro definování různých akcí, které mají být provedeny v určeném pořadí za určitých podmínek. Aby bylo zajištěno, že jsou vaše konfigurační soubory správné, poskytuje GitLab testovací nástroj pro validaci. Ve své instanci GitLabu, v repozitáři projektu, můžete navštívit rozhraní CI lint pro validaci vašeho .gitlab-ci.yml. Klikněte na CI/CD v levém navigačním menu a klikněte na tlačítko CI lint na stránce, která se zobrazí:

Direktivy v konfiguračním souboru jsou popsány níže.

• Základní Docker obraz

První řádek v konfiguračním souboru deklaruje Docker obraz, který by měl být použit ke spuštění testů. Vzhledem k tomu, že sestavujeme aplikaci Node.js, použijeme nejnovější obraz Node.js:

• Fáze

Poté definujeme různé fáze, kterými chceme, aby naše testy průběžné integrace prošly. Máme pouze dvě fáze:

Při definování názvů fází jsou názvy jako build nebo test vybrány náhodně – můžete si vybrat jakýkoli název. Fáze však musíte správně seřadit, protože to určuje tok provádění. V našem případě se úlohy ve fázi build spustí před úlohami ve fázi test . GitLab runner spustí úlohy ve stejné fázi paralelně a před spuštěním úloh v další fázi počká na dokončení všech úloh.

• Cache

Definice cache je zahrnuta pro určení souborů a adresářů, které budou uloženy do mezipaměti nebo uloženy pro pozdější použití mezi spuštěními úloh:

Definování ukládání do mezipaměti pomáhá minimalizovat čas potřebný ke spuštění úloh, které závisí na prostředcích, u nichž je nepravděpodobné, že se mezi spuštěními změní. Určujeme adresář node_modules pro uložení do mezipaměti. Toto je adresář, do kterého npm instaluje závislosti pro projekt.

• Úlohy

V konfiguraci máme dvě úlohy:

• install_dependencies

Při pojmenovávání úloh si můžete vybrat jakýkoli název. Doporučuje se však zvolit popisný název, protože se používají v uživatelském rozhraní GitLabu – to může být užitečné při ladění. Na webu najdete většinu konfigurací kombinujících npm install s příkazy ve fázi testování. Oddělili jsme je pouze proto, abychom pomohli demonstrovat, jak spolu úlohy komunikují, protože se jedná o poměrně malý projekt. stage direktiva označuje tuto úlohu jako build – spouští se ve fázi build stage.

The script určuje příkazy, které se mají spustit při provádění této úlohy. Více příkazů můžete zadat přidáním řádků v rámci bloku script. Samozřejmě musíte dbát na správné odsazení a mít na paměti pořadí, v jakém by měly být skripty spouštěny.

The artifacts určuje soubory nebo cesty k adresářům, které se mají uložit a sdílet mezi fázemi. Opět připomínáme, že správné pořadí fází je zásadní pro zajištění toho, aby ostatní soubory měly to, co potřebují ke svému spuštění. Příkaz npm install nainstaluje závislosti do adresáře node_modules. Tím, že jej deklarujeme v artefaktech, jej zpřístupníme pro úlohy spouštěné v následujících fázích. Soubory jsou také k dispozici v uživatelském rozhraní GitLabu, pokud byste si je chtěli stáhnout.

• test_with_mocha

Tato úloha se spouští ve fázi test. Vzhledem k tomu, že tato úloha běží po spuštění úlohy ve fázi build, budou artefakty deklarované ve fázi build (což jsou závislosti pro naši aplikaci) k dispozici pro fázi test. Blok script určuje příkazy npm pro spuštění našich testů. Nejprve spustíme naši aplikaci a poté proti ní spustíme testy. Spuštěním těchto příkazů se aktivují příkazy specifikované v sekci bloku skriptů package.json v sekci bloku skriptů:
Tím byste měli získat základní představu o souboru .gitlab-ci.yml. Říkáme základní, protože se jedná pouze o statickou aplikaci hello world. Dále se podívejme, jak můžeme spustit nový běh CI.

Krok 3: Spuštění běhu GitLab CI

Jistě vás potěší, že jakmile váš repozitář obsahuje soubor .gitlab-ci.yml, jakékoli nové commity, které do něj nahrajete, spustí nový běh průběžné integrace (Continuous Integration). V případě self-managed instancí GitLabu, pokud nemáte nakonfigurovaný GitLab runner, bude běh CI nastaven na „pending“.

GitLab SaaS poskytuje uživatelům sdílené runnery, které mohou převzít jejich úlohy a automaticky je spustit. To je možné pouze v případě, že jsou sdílené runnery volné a nepřekročili jste svou kvótu. V GitLab SaaS si můžete vybrat, zda chcete, aby váš repozitář používal shared runners, nebo ne, a to tak, že přejdete na stránku vašeho projektu Settings > CI / CD, jak je znázorněno na snímku obrazovky níže. Na této stránce najdete také informace o pokynech k instalaci GitLab runneru, kterými se budeme podrobněji zabývat v dalším kroku:

Nyní proveďme malou změnu, abychom spustili běh CI. Přejděte zpět do repozitáře svého projektu GitLab node_pipeline:

Klikněte na soubor README.md zvýrazněný výše, abyste si jej prohlédli:

Kliknutím na tlačítko ‘Edit’ otevřete soubor pro úpravy v prohlížeči a přidejte nějaký text:

Jakmile přidáte nějaký text, přejděte dolů a kliknutím na tlačítko Commit changes uložte změny. Zprávu ke commitu můžete upravit podle svého uvážení. Při spuštění pipeline se zobrazí jako název v uživatelském rozhraní GitLabu. Ponechali jsme ji jako Update README.md, protože je to docela popisné:

Po odeslání změn se vraťte na hlavní stránku projektu. Všimnete si malé paused icon u nejnovějšího commitu. Pokud nad ikonu najedete myší, zobrazí se: ‘Pipeline:pending’:

To znamená, že běh CI byl spuštěn. Testy však ještě nebyly spuštěny. V navigační nabídce vlevo klikněte na CI/CD, a poté vyberte Pipelines. Tím se otevře stránka s dalšími podrobnostmi o pipeline. Můžete vidět, že CI čeká a je označeno jako zaseknuté:

Chcete-li získat více podrobností o běhu, klikněte na stav pending. Uvidíte níže uvedené zobrazení, které ukazuje různé fáze běhu a jednotlivé úlohy propojené s každou fází:

Můžete také kliknout na jednotlivé úlohy a zobrazit si podrobnější detaily, například co způsobuje zpoždění. V případě neúspěšných spuštění zde uvidíte, co způsobilo selhání úlohy:

Zpráva indikuje, že úloha uvízla, protože jste nenakonfigurovali žádné aktivní runnery, které by tuto úlohu mohly provést. To provedeme v dalším kroku. Jakmile runner zpřístupníte, úloha se začne spouštět automaticky. Při spuštění úlohy uvidíte výstup v tomto rozhraní a také další stažitelné artefakty vygenerované během běhu úlohy.

Krok 4: Nastavení služby GitLab CI Runner

Nyní je čas využít druhý server, který jsme deklarovali v sekci Požadavky tohoto návodu. Na tomto serveru nainstalujeme a nastavíme službu GitLab runner. Službu můžete nasadit tak, aby spouštěla více instancí runnerů pro různé projekty na GitLabu.

Máte možnost nasadit runner na stejný server, který hostuje vaši self-managed instanci GitLabu. Aby se však zajistilo, že instance nebude omezena prostředky, je lepší nastavit samostatnou instanci CI runneru. Ať už se rozhodnete pro jakoukoli konfiguraci, musí být nainstalován Docker pro izolaci testovacích prostředí.

Proces instalace GitLab CI runneru je srovnatelný s procesem pro instalaci self-managed instance GitLabu. Začneme stažením skriptu pro přidání oficiálního repozitáře GitLabu do zdrojů apt pomocí následujícího příkazu:

Po výzvě zadejte heslo uživatele root. Dále můžete spustit příkaz pro instalaci nejnovějšího GitLab CI runneru:

Výše uvedený příkaz nainstaluje a zaregistruje službu runneru připravenou k použití vašimi projekty.

Krok 5: Získání registračních tokenů a propojení GitLab Runneru

Chcete-li nastavit GitLab CI runner tak, aby začal přijímat úlohy, potřebujete token GitLab runneru. Ten je nutný k tomu, aby se runner mohl autentizovat vůči vaší instanci serveru GitLab. Existují dva typy tokenů v závislosti na tom, jak chcete runner používat: specifický pro projekt a sdílený runner.

Runnery specifické pro projekt jsou použitelné, pokud máte na runner jedinečné požadavky. Pokud máte například definice nasazení ve svém souboru gitlab-ci.yml s jedinečnými tokeny, pak může být pro správnou autentizaci do prostředí nasazení doporučen specifický runner. Dalším aspektem je, zda vaše fáze kontinuální integrace obsahují procesy náročné na prostředky. V takovém případě by bylo ideální zvolit runner specifický pro projekt. Upozorňujeme, že runner specifický pro projekt nepřijímá úlohy z jiných projektů.

Sdílené runnery jsou univerzální a mohou být použity více projekty. Instance GitLab SaaS hostovaná na GitLab Inc má některé sdílené runnery, které automaticky převezmou vaše pipeline, jak je vysvětleno v Kroku tři. Runnery přebírají úlohy z vašich konfigurací na základě algoritmu, který zohledňuje počet úloh aktuálně prováděných pro každý projekt. Sdílený runner je flexibilnější než specifický runner. Lze jej nakonfigurovat z administrátorského účtu instance GitLabu. Podívejme se, jak můžeme získat tokeny pro oba runnery.

• Registrace runneru specifického pro projekt

Chcete-li zaregistrovat runner specifický pro projekt, otevřete svůj projekt ve své instanci GitLabu nebo na účtu GitLab SaaS. V navigační nabídce vlevo klikněte na položku Settings a vyberte možnost CI/CD:

Poté sjeďte dolů k sekci Runners a kliknutím na tlačítko tuto sekci rozbalte:

Levá strana vysvětluje, jak zaregistrovat runner specifický pro projekt. Toto je zobrazení instance GitLab SaaS. Můžete také nakonfigurovat automatické runnery pomocí Kubernetes, ale v tomto návodu budeme nastavovat runner ručně:

Dále se musíte zaměřit na sekci, kde je uveden token pro tento projekt. U self-managed instance GitLabu se v URL zobrazí doména serveru, na kterém vaše instance GitLabu běží:

Sdílené runnery pro tento projekt můžete zakázat přepnutím přepínače v pravé části pod Shared Runners. Poté si zkopírujte zobrazený registrační token do poznámkového bloku, protože jej použijeme později.

• Registrace sdíleného runneru

Chcete-li zaregistrovat sdílený runner, musíte se přihlásit do své self-managed instance GitLabu jako administrátor. Pro přístup do administrátorského panelu klikněte na ikonu klíče v horním navigačním menu:

V Admin Panelu, klikněte na Runners v sekci Overview v levém menu. Tím se otevře stránka s pokyny pro konfiguraci Shared Runners:

Zkopírujte registrační token zobrazený na pravé straně pod Set up a shared Runner manually. Tento token použijete k registraci runneru v dalším kroku.

• Propojení GitLab CI Runneru s instancí GitLabu

V tomto kroku propojíte svou instanci GitLabu s CI runnerem. Přihlaste se zpět na server, kde jste nainstalovali službu GitLab runner ve Kroku čtyři. Chcete-li spustit proces registrace runneru, zadejte do terminálu následující příkaz:

Příkaz vás vyzve k zodpovězení řady otázek:

• Zadejte URL instance GitLabu (například https://gitlab.com/):

Zadejte doménové jméno své instance GitLabu pomocí https:// pro specifikaci SSL.

• Zadejte registrační token:

Zadejte svůj registrační token. Zde si vyberete, zda chcete, aby byl tento runner specifický pro projekt, nebo sdílený. Pro kteroukoli z možností můžete zadat pouze jeden z tokenů, které jste si zkopírovali dříve.

• Zadejte popis runneru:

Zvolte popisný název pro svůj CI runner, jak se bude zobrazovat v uživatelském rozhraní instance GitLabu.

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

Zde máte možnost vybrat executor pro spouštění úloh. Zadejte Docker.

• Zadejte tagy pro runner (oddělené čárkou):

Toto je volitelné. Můžete zadat libovolné názvy tagů, například závislosti, které tento runner obsahuje. Prozatím to můžete nechat prázdné.

• Zadejte výchozí Docker image (například ruby:2.6):

Zde se očekává, že určíte výchozí univerzální image použitý ke spuštění úloh v případě, že soubor gitlab-ci.yml neurčuje žádný image. Zadejte alpine:latest, protože se jedná o malý, univerzální a bezpečný image. Stiskněte enter a runner se automaticky zaregistruje a spustí:

Chcete-li zobrazit seznam aktuálně dostupných runnerů, zadejte následující příkaz:

Krok 6: Potvrzení úspěšného propojení CI Runneru v GitLabu

Dále se vraťte do prohlížeče a navštivte stránku svého projektu v instanci GitLabu. V závislosti na tom, kolik minut uplynulo od registrace runneru, můžete vidět, že úloha právě běží:

Nebo již mohla být dokončena:

Poté přejděte na stránku Pipelines buď prostřednictvím levého menu CI/CD > Pipelines, nebo kliknutím na ikonu running, passed, nebo failed (pokud pipeline narazila na chyby), abyste viděli stav běhu CI. Zde vidíme, že jedna z fází (build stage) úspěšně proběhla, zatímco jedna stále běží:

V tabulce pod hlavičkou Stages klikněte na jednu z ikon fází pro zobrazení souvisejících úloh:

Poté klikněte na úlohu ve vyskakovacím okně pro zobrazení podrobností:

Úloha se spustila a můžete vidět průběh, když příkaz npm instaloval závislosti. Na pravé straně si můžete prohlédnout další související informace. Máte možnost stáhnout si artefakty z úlohy. V rozbalovací nabídce můžete také přepínat mezi fázemi a zobrazit si další úlohy.

Zde si můžete prohlédnout naše testovací případy, které se zobrazí, když vyberete úlohu ve fázi testování:

Dostupné runnery

Pokud v levém menu kliknete na Settings > CI/CD, a rozbalíte Runners sekci byste měli vidět runnera, kterého jste právě zaregistrovali. V závislosti na tom, zda jste zadali token specifický pro projekt, nebo sdílený token, se runner zobrazí v příslušné sekci.

Zde můžete vidět, že jsme zaregistrovali token specifický pro projekt. Runner se zobrazí pod Specifické runnery:

Závěr

V tomto návodu jste se naučili, jak můžete automatizovat své testy pomocí GitLab CI. Začali jsme nastavením projektu aplikace Node.js na GitLabu. Projekt obsahoval několik testovacích případů a gitlab-ci.yml. Dozvěděli jsme se, že GitLab používá gitlab-ci.yml soubor k určení toho, co má dělat, když je spuštěn. Soubor gitlab-ci.yml je pouze konfigurační soubor, který obsahuje instrukce pro sestavení a testování aplikací, napsaný v YAML formátu, kterému runner GitLab CI rozumí.

Podařilo se nám také nastavit GitLab CI runner na samostatném hostiteli. Zaregistrovali jsme ho, aby přijímal úlohy z našich instancí GitLabu, kdykoli dojde ke spuštění. I když se jednalo o jednoduchý projekt, na základě těchto informací můžete nastavit pipeline pro složité projekty. Kroky pro přidání projektu do GitLabu a propojení GitLab CI runneru zůstávají stejné. Mění se pouze instrukce a fáze v gitlab-ci.yml souboru.

Příjemnou práci!