Hogyan állítsuk be a GitLab folyamatos integrációs (CI) pipeline-okat Ubuntu 20.04-en

Minden fejlesztő tisztában van azzal, hogy a verziókezelés mennyire kulcsfontosságú a szoftverfejlesztési életciklusban. Lehetővé teszi, hogy többen dolgozzanak egyidejűleg egyetlen projekten, miközben mindenki saját másolatot tart fenn a kódról, és maga dönti el, mikor osztja meg azt a csapat többi tagjával. Ennek eléréséhez a fejlesztők Git adattárakat használnak a verziókezelés segítésére. GitLab egy webalapú Git-adattár, amely több mint egy verziókezelő eszköz. Emellett DevOps eszközöket, hibakövetést (issue-tracking), folyamatos integrációt és telepítést is biztosít.

A GitLab három opciót kínál, amelyek közül választhat: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) és GitLab SaaS. A GitLab CE és a GitLab EE saját üzemeltetésű (self-managed) megoldások. Ez azt jelenti, hogy Önnek kell letöltenie, telepítenie és kezelnie a GitLab példányt. A GitLab SaaS-t a GitLab Inc. üzemelteti, így nem kell aggódnia a telepítés miatt a használatához. Mindössze annyit kell tennie, hogy létrehoz egy GitLab-fiókot és már kezdheti is.

Ebben az útmutatóban megmutatjuk, hogyan állíthat be folyamatos integrációs (Continuous Integration) folyamatokat a GitLab CI segítségével, hogy figyelje az adattárak változásait, és automatizált teszteket futtasson az új kód ellenőrzésére. Első lépésként beállítunk egy Git-adattárat a kód tárolására. Ezután konfigurálunk egy CI-folyamatot az adattárba történő commitok figyelésére, és elindítunk egy CI runnert a tesztek futtatásához egy elkülönített Docker-konténerben.

Előfeltételek

A kezdéshez szüksége lesz egy szerverre, amelyen a GitLab verziókezelő szoftver fut. Mind a saját üzemeltetésű GitLab, mind a SaaS képes automatizált tesztek futtatására. Az ingyenes SaaS opciókban azonban vannak bizonyos korlátok a tesztek számára elérhető percek és erőforrások tekintetében. Nagyobb szabadsága van, ha a saját üzemeltetésű opciókat használja, mert annyi erőforrást rendelhet a GitLab példányához, amennyit csak szeretne. Kövesse az saját Git-adattárak üzemeltetése a GitLab segítségével című útmutatónkat, hogy megtudja, hogyan állíthatja be saját GitLab példányát.

Szüksége lesz legalább egy szerverre, amelyet GitLab CI runnerként használhat. Ha szeretné, természetesen több szervere is lehet. Ha saját üzemeltetésű GitLab példányt állított be, használhatja ugyanazt a szervert is, de mi inkább egy külön szerver beállítását javasoljuk a CI runner számára. Ez a Hogyan állítsa be Ubuntu szerverét című útmutató jó kiindulópont.

A GitLab CI runner szervereken telepítve kell lennie a Dockernek, hogy a tesztelési környezeteket Docker-konténerben különíthesse el. Van egy útmutatónk a Hogyan telepítsük és üzemeltessük a Dockert Ubuntun témában, amely segíthet ennek a követelménynek a teljesítésében.

Most, hogy minden megvan, amire szükségünk van, kezdjük el!

1. lépés: Projekt létrehozása egy GitLab példányon

Első lépésként létrehozunk egy projekt-adattárat a GitLabon. Ezt az útmutatót egy Node.js alkalmazásra fogjuk alapozni. Mivel nem szeretnénk a projektfájlokat a semmiből létrehozni, kihasználjuk a GitLab által kínált eszközt, amellyel más verziókezelő adattárakból importálhatunk projekteket. Az importált alkalmazás egy egyszerű „hello world” alkalmazás, amely az Express.js – egy minimalista webes keretrendszer Node.js alkalmazásokhoz segítségével készült. A teszteket a Mocha és Chai – ezek egységtesztelésre használt JavaScript keretrendszerek. A Mocha lehetővé teszi az aszinkron tesztelést, a tesztlefedettségi jelentéseket, és társítható más assertion (állítás) könyvtárakkal. A Chai egy assertion könyvtár. Bármilyen tesztkeretrendszerrel párosítható, a mi esetünkben a Mochát fogjuk párosítani a Chai-jal.

Most, hogy ismeri a projektünk alapjait, jelentkezzen be a GitLab példányába (legyen az saját üzemeltetésű vagy SaaS), kattintson a felső navigációs sávon található ‘plus’ ikonra, majd válassza az ‘New project’ lehetőséget. Alternatív megoldásként, ha a fiókja kezdőlapjának tetejére görget, rákattinthat az ‘New project’ gombra:

Az új projekt oldalon kattintson az Import project fülre:

Ezután a megnyíló oldalon kattintson a Repo by URL gombra:

Bár létezik GitHub importálási lehetőség is, ezt nem fogjuk használni, mivel személyes hozzáférési tokent (Personal access token) igényel. Nekünk nem kell személyes hozzáférési tokeneket beállítanunk, mivel nyilvános adattárral dolgozunk, és a puszta URL-lel történő importálás rendkívül egyszerű.

Ezután másolja ki a következő URL-t, és illessze be a Git Repository URL mezőbe:

Így kell kinéznie:

Hagyja a tárolót Private beállításon, és kattintson a Create project gombra, ha végzett. Várjon néhány másodpercet, amíg a projekt importálása befejeződik a GitHubról, és meg nem jelenik a GitLab tárolói között. A GitLab a projektet a GitHub repository projektével megegyező részletekkel importálja.

2. lépés: A .gitlab-ci.yml fájl elemzése

A GitLab CI átvizsgál minden GitLab-on lévő tárolót egy .gitlab-ci.yml nevű fájlt keresve, hogy tudja, hogyan kell futtatnia az automatizált teszteket. Az imént importált tárolóban látható egy .gitlab-ci.yml fájl a projektfájlok között. További információt találhat a GitLab CI yml fájlról a hivatalos Keyword reference for the .gitlab-ci.yml file docs.

A GitLab tároló felületén kattintson a .gitlab-ci.yml fájlra, hogy megnyissa a böngészőben. Így kell kinéznie:

Figyelje meg a sorok behúzását. A fájl szigorú GitLab CI YAML konfigurációs szintaxist követ, hogy meghatározza a végrehajtandó műveleteket egy megadott sorrendben, bizonyos feltételek mellett. A konfigurációs fájlok helyességének ellenőrzéséhez a GitLab egy tesztelési segédprogramot biztosít a validáláshoz. A GitLab példányán belül, a projekt tárolójában meglátogathatja a CI lint felületet a .gitlab-ci.yml validálásához. Kattintson a CI/CD lehetőségre a bal oldali navigációs menüben, majd kattintson a CI lint gombra a megjelenő oldalon:

A konfigurációs fájlban található direktívákat az alábbiakban tárgyaljuk.

• Alap Docker-rendszerkép

A konfigurációs fájl első sora deklarálja azt a Docker-rendszerképet, amelyet a tesztek futtatásához kell használni. Mivel Node.js alkalmazást építünk, a legújabb Node.js rendszerképet használjuk:

• Szakaszok

Ezután meghatározzuk a különböző szakaszokat, amelyeken a folyamatos integrációs tesztjeinknek át kell menniük. Csak két szakaszunk van:

A szakasznevek meghatározásakor az olyan nevek, mint a build vagy test tetszőlegesen választhatók – bármilyen nevet megadhat, amit szeretne. Azonban a szakaszokat megfelelően kell sorba rendeznie, mert ez határozza meg a végrehajtás menetét. A mi esetünkben a build szakaszban lévő feladatok a test szakasz feladatai előtt futnak le. A GitLab runner az azonos szakaszban lévő feladatokat párhuzamosan hajtja végre, és megvárja az összes feladat befejezését, mielőtt elkezdené a következő szakasz feladatainak végrehajtását.

• Gyorsítótár

A cache definíció arra szolgál, hogy meghatározza azokat a fájlokat és könyvtárakat, amelyek gyorsítótárazásra vagy mentésre kerülnek a feladatok futtatásai közötti későbbi használatra:

A gyorsítótárazás meghatározása segít minimalizálni a futtatások között valószínűleg nem változó erőforrásokra támaszkodó feladatok futtatási idejét. Megadjuk a node_modules könyvtárat a gyorsítótárazáshoz. Ez az a könyvtár, amelybe az npm telepíti a projekt függőségeit.

• Feladatok

Két feladatunk van a konfigurációban:

• install_dependencies

A feladatok elnevezésekor szabadon választhat bármilyen nevet. Ajánlott azonban leíró nevet választani, mivel ezek jelennek meg a GitLab felületén – ez hasznos lehet a hibakeresés során. A weben a legtöbb konfigurációban azt fogja látni, hogy kombinálják az npm install a test szakasz parancsaival. Csak azért választottuk külön őket, hogy bemutassuk, hogyan lépnek interakcióba a feladatok, mivel ez egy meglehetősen kis projekt. A stage direktíva build-ként jelöli meg ezt a feladatot – a build stage.

A script direktíva határozza meg a feladat végrehajtása során futtatandó parancsokat. Több parancsot is megadhat, ha új sorokat ad hozzá a script blokkon belül. Természetesen ügyelnie kell a megfelelő behúzásra, és észben kell tartania a szkriptek végrehajtási sorrendjét.

Az artifacts direktíva határozza meg a mentendő és a szakaszok között megosztandó fájlokat vagy könyvtárútvonalakat. Ismételten emlékeztetünk arra, hogy a szakaszok megfelelő sorrendbe állítása kulcsfontosságú annak biztosításához, hogy a többi fájlnak meglegyen a végrehajtáshoz szükséges feltétele. Az npm install parancs telepíti a függőségeket a node_modules könyvtárba. Az artifacts-ban való deklarálással elérhetővé tesszük a későbbi szakaszokban végrehajtott feladatok számára. A fájlok a GitLab felületén is elérhetők, ha le szeretné tölteni őket.

• test_with_mocha

Ez a feladat a test szakaszban fut. Mivel ez a feladat a build szakaszban futó feladat után fut le, a build szakaszban deklarált artifactok (amelyek az alkalmazásunk függőségei) elérhetők lesznek a test szakasz számára. A script blokk határozza meg a tesztek futtatásához szükséges npm parancsokat. Először elindítjuk az alkalmazást, majd lefuttatjuk a teszteket az alkalmazáson. Ezen parancsok futtatása elindítja a package.json script blokk szakaszában megadott parancsokat:
Ezzel már rendelkeznie kell egy alapvető megértéssel a .gitlab-ci.yml fájlról. Azért mondjuk, hogy alapvető, mert ez csak egy statikus hello world alkalmazás. Következő lépésként lássuk, hogyan indíthatunk el egy új CI futást.

3. lépés: GitLab CI futás indítása

Örömmel fogja hallani, hogy amint a tárhelye tartalmazza a .gitlab-ci.yml fájlt, minden új commit, amit feltol rá, egy új folyamatos integrációs (Continuous Integration) futást fog elindítani. Saját üzemeltetésű GitLab példányok esetén, ha nem konfigurált GitLab runnert, a CI futás állapota „pending” (függőben lévő) lesz.

A GitLab SaaS biztosít a felhasználóknak néhány megosztott runnert (shared runners), amelyek automatikusan átvehetik és végrehajthatják a feladataikat. Ez csak akkor lehetséges, ha a megosztott runnerek szabadok, és Ön nem lépte túl a kvótáját. A GitLab SaaS-ban kiválaszthatja, hogy szeretné-e, hogy a tárhelye használja-e a shared runners opciót vagy sem, ha ellátogat a projektje Settings > CI / CD oldalára, ahogy az az alábbi képernyőképen látható. Ezen az oldalon információkat talál a GitLab runner telepítési útmutatójáról is, amelybe a következő lépésben mélyedünk el:

Most tegyünk egy kis változtatást a CI futás elindításához. Navigáljon vissza a node_pipeline GitLab projekt tárhelyére:

Kattintson a fent kiemelt README.md fájlra a megtekintéséhez:

Kattintson az ‘Edit’ gombra a fájl böngészőben történő szerkesztéséhez, és adjon hozzá valamilyen szöveget:

Miután hozzáadott valamilyen szöveget, görgessen le, és kattintson a Commit changes gombra a módosítások mentéséhez. A commit üzenetet tetszés szerint módosíthatja. Ez címként fog megjelenni a GitLab felületén, amikor a pipeline fut. Mi meghagytuk Update README.md formában, mivel ez meglehetősen leíró jellegű:

Miután végrehajtotta a commitot, térjen vissza a projekt főoldalára. Észre fog venni egy kis paused icon ikont a legutóbbi commit mellett. Ha az egeret az ikon fölé viszi, a következő jelenik meg: ‘Pipeline:pending’:

Ez azt jelenti, hogy a CI futás elindult. A tesztek azonban még nem futottak le. A bal oldali navigációs menüben kattintson a CI/CD, majd válassza a Pipelines. lehetőségre. Ez megnyit egy oldalt, amely további részleteket mutat a pipeline-ról. Láthatja, hogy a CI függőben van (pending) és elakadtként (stuck) van megjelölve:

A futással kapcsolatos további részletekért kattintson a pending állapotra. Az alábbi nézet fogadja majd, amely bemutatja a futás különböző szakaszait (stages) és az egyes szakaszokhoz kapcsolódó egyedi feladatokat (jobs):

Az egyes feladatokra kattintva részletesebb információkat is megtekinthet, például azt, hogy mi okozza a késéseket. Sikertelen futások esetén itt láthatja, hogy mi okozta a feladat meghiúsulását:

Az üzenet azt jelzi, hogy a feladat elakadt, mert nem konfigurált olyan aktív futtatót (runner), amely képes lenne végrehajtani ezt a feladatot. Ezt a következő lépésben fogjuk megtenni. Amikor elérhetővé tesz egy futtatót, a feladat végrehajtása automatikusan elindul. Amikor egy feladat fut, a kimenetet ezen a felületen fogja látni, valamint a feladat futása során generált egyéb letölthető artefaktumokat is.

4. lépés: A GitLab CI Runner szolgáltatás beállítása

Most jött el az ideje, hogy használatba vegyük a második szervert, amelyet a Előfeltételek szakaszban adtunk meg ebben az útmutatóban. Ezen a szerveren fogunk telepíteni és beállítani egy GitLab runner szolgáltatást. A szolgáltatást úgy is telepítheti, hogy több runner példányt futtasson a GitLab különböző projektjeihez.

Lehetősége van arra is, hogy a runnert ugyanarra a szerverre telepítse, amely a saját üzemeltetésű GitLab példányát is kiszolgálja. Azonban annak biztosítása érdekében, hogy a példányt ne korlátozzák az erőforrások, célszerűbb egy különálló CI runner példányt beállítani. Bármelyik konfigurációt is választja, a Dockernek telepítve kell lennie a tesztkörnyezetek elszigeteléséhez.

A GitLab CI runner telepítésének folyamata hasonló a saját üzemeltetésű GitLab példány telepítéséhez. Első lépésként letöltünk egy szkriptet, amellyel hozzáadjuk a hivatalos GitLab tárolót az apt forrásokhoz a következő paranccsal:

Adja meg a root jelszavát, amikor a rendszer kéri. Ezután futtathatja a parancsot a legújabb GitLab CI runner telepítéséhez:

A fenti parancs telepíti és regisztrálja a runner szolgáltatást, amely így készen áll a projektjei általi használatra.

5. lépés: Regisztrációs tokenek beszerzése és a GitLab Runner összekapcsolása

Ahhoz, hogy beállítson egy GitLab CI runnert a feladatok fogadására, szüksége van egy GitLab runner tokenre. Erre azért van szükség, hogy a runner hitelesíteni tudja magát a GitLab szerverpéldányánál. Kétféle token létezik attól függően, hogyan szeretné használni a runnert: projektspecifikus és osztott (shared) runner.

A projektspecifikus runnerek akkor alkalmazhatók, ha egyedi követelményei vannak a runnerrel szemben. Például, ha a telepítési definíciók a gitlab-ci.yml fájlban egyedi tokenekkel rendelkeznek, akkor egy specifikus runner javasolt a telepítési környezetbe való helyes hitelesítéshez. Egy másik szempont, ha a folyamatos integrációs szakaszok erőforrás-igényes folyamatokat tartalmaznak. Ebben az esetben ideális választás egy projektspecifikus runner. Vegye figyelembe, hogy a projektspecifikus runner nem fogad el feladatokat más projektektől.

Az osztott (shared) runnerek általános célúak, és több projekt is használhatja őket. A GitLab Inc által üzemeltetett GitLab SaaS példány rendelkezik néhány osztott runnerrel, amelyek automatikusan felveszik a folyamatokat (pipelines), ahogy azt a Harmadik lépésben elmagyaráztuk. A runnerek egy olyan algoritmus alapján vesznek át feladatokat a konfigurációkból, amely figyelembe veszi az egyes projektekhez jelenleg végrehajtás alatt álló feladatok számát. Az osztott runner rugalmasabb, mint a specifikus runner. A GitLab példány adminisztrátori fiókjából konfigurálható. Lássuk, hogyan szerezhetjük be a tokeneket mindkét runnerhez.

• Projektspecifikus runner regisztrálása

Projektspecifikus runner regisztrálásához nyissa meg a projektjét a GitLab példányában vagy a GitLab SaaS fiókjában. A bal oldali navigációs menüben kattintson a Settings elemre, majd válassza a CI/CD lehetőséget:

Ezután görgessen le a Runners szakaszhoz, és kattintson a gombra a szakasz kibontásához:

A bal oldal elmagyarázza, hogyan kell regisztrálni egy projektspecifikus runnert. Ez a GitLab SaaS példány nézete. Automatikus runnereket is konfigurálhat a Kubernetes segítségével, de ebben az útmutatóban a manuális runnert mutatjuk be:

Ezután arra a szakaszra kell összpontosítania, ahol a projekthez tartozó tokent kapja. Saját üzemeltetésű GitLab példány esetén az URL azon szerver tartománynevét fogja mutatni, amelyen a GitLab példánya fut:

Kikapcsolhatja a megosztott runnereket ehhez a projekthez a jobb oldali szakaszban található kapcsoló átváltásával a következő alatt: Shared Runners. Ezután másolja ki a megjelenített regisztrációs tokent a jegyzettömbjébe, mert később szükségünk lesz rá.

• Megosztott runner regisztrálása

Megosztott runner regisztrálásához adminisztrátorként kell bejelentkeznie a saját üzemeltetésű GitLab példányába. Az adminisztrációs panel eléréséhez kattintson a csavarkulcs ikonra a felső navigációs menüben:

Az Adminisztrációs panel oldalon kattintson a Runners lehetőségre a Overview szakaszában a bal oldali menüben. Ez megnyit egy oldalt a Shared Runners konfigurációs utasításaival:

Másolja ki a jobb oldalon, a Set up a shared Runner manually alatt megjelenő regisztrációs tokent. Ezt a tokent fogja használni a runner regisztrálásához a következő lépésben.

• GitLab CI Runner összekapcsolása egy GitLab példánnyal

Ebben a lépésben összekapcsolja a GitLab példányát a CI runnerrel. Jelentkezzen be újra arra a szerverre, amelyre a GitLab runner szolgáltatást telepítette a Negyedik lépésben. A runner regisztrációs folyamatának elindításához írja be a következő parancsot a terminálba:

A parancs egy sor kérdést tesz fel Önnek:

• Adja meg a GitLab példány URL-jét (például https://gitlab.com/):

Adja meg a GitLab példány tartománynevét a https:// használatával az SSL megadásához.

• Adja meg a regisztrációs tokent:

Adja meg a regisztrációs tokent. Itt választhatja ki, hogy ez a runner projektspecifikus vagy megosztott legyen. A korábban kimásolt tokenek közül csak az egyiket adhatja meg a két opció egyikéhez.

• Adja meg a runner leírását:

Válasszon egy leíró nevet a CI runnernek, mivel ez fog megjelenni a GitLab példány felületén.

• Adjon meg egy végrehajtót (executor): custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Itt lehetőségeket kínál fel a feladatok futtatásához szükséges végrehajtó kiválasztására. Írja be: Docker.

• Adja meg a runner címkéit (vesszővel elválasztva):

Ez opcionális. Megadhat bármilyen címkenevet, például a runner által tartalmazott függőségeket. Egyelőre üresen is hagyhatja.

• Adja meg az alapértelmezett Docker-képet (például ruby:2.6):

Itt meg kell adnia egy alapértelmezett, általános célú képet, amelyet a feladatok futtatásához használ, ha a gitlab-ci.yml fájl nem határoz meg képet. Írja be: alpine:latest, mivel ez egy kicsi, általános célú és biztonságos kép. Nyomja meg az Entert, és a runner automatikusan regisztrálásra és elindításra kerül:

A jelenleg elérhető runnerek listájának megtekintéséhez írja be a következő parancsot:

6. lépés: A CI Runner sikeres összekapcsolásának ellenőrzése a GitLabban

Ezután térjen vissza a böngészőhöz, és keresse fel a projekt oldalát a GitLab példányban. Attól függően, hogy hány perc telt el a runner regisztrálása óta, láthatja, hogy a feladat jelenleg fut:

Vagy már be is fejeződött:

Ezt követően navigáljon a Pipelines oldalra a bal oldali menüben a CI/CD > Pipelines útvonalon, vagy kattintson a running, passed, vagy failed ikonra (ha a pipeline hibákba ütközött) a CI futás állapotának megtekintéséhez. Itt láthatjuk, hogy az egyik szakasz (build stage) sikeresen lefutott, míg egy másik még fut:

A táblázatban a Stages fejléc alatt kattintson az egyik szakasz ikonjára a kapcsolódó feladatok megtekintéséhez:

Ezután kattintson egy feladatra a felugró ablakban a részletek megtekintéséhez:

A feladat lefutott, és láthatja a folyamatot, amikor az npm parancs telepítette a függőségeket. A jobb oldalon egyéb kapcsolódó információkat láthat. Lehetősége van letölteni a feladatból származó artefaktumokat (artifacts). A legördülő menüből a szakaszok között is válthat a többi feladat megtekintéséhez.

Itt láthatja a teszteseteinket, amelyek akkor jelennek meg, amikor kiválasztja a feladatot a tesztelési szakaszban (test stage):

Available Runners

A bal oldali menüben, ha a Settings > CI/CD lehetőségre kattint, és kibontja a Runners szekcióban látnia kell az imént regisztrált runnert. Attól függően, hogy projekt-specifikus tokent vagy megosztott tokent adott meg, a runner a megfelelő szekcióban fog megjelenni.

Itt látható, hogy egy projekt-specifikus tokent regisztráltunk. A runner a következő alatt jelenik meg: Specific Runners:

Összegzés

Ebben az útmutatóban megtanulta, hogyan automatizálhatja tesztjeit a GitLab CI segítségével. Kezdésként beállítottunk egy Node.js alkalmazásprojektet a GitLabon. A projekt tartalmazott néhány tesztesetet és egy gitlab-ci.yml fájlt. Megtanultuk, hogy a GitLab a gitlab-ci.yml fájlt használja annak meghatározására, hogy mit tegyen, amikor aktiválódik. A gitlab-ci.yml fájl csupán egy konfigurációs fájl, amely az alkalmazások építésére és tesztelésére vonatkozó utasításokat tartalmazza, YAML formátumban, amelyet egy GitLab CI runner meg tud érteni.

Sikerült egy GitLab CI runnert is beállítanunk egy külön gazdagépen. Regisztráltuk, hogy feladatokat fogadjon a GitLab példányainkból, amikor csak trigger történik. Bár ez egy egyszerű projekt volt, ezekre az információkra építve összetett projektekhez is beállíthat folyamatokat. A projekt GitLabhoz való hozzáadásának és a GitLab CI runner összekapcsolásának lépései ugyanazok maradnak. Ami változik, azok az utasítások és a szakaszok a gitlab-ci.yml fájlban.

Boldog kódolást!