GitLab Continuous Integration (CI)-pipelines opzetten op Ubuntu 20.04

Elke ontwikkelaar begrijpt hoe cruciaal versiebeheer is voor de levenscyclus van softwareontwikkeling. Het stelt meerdere mensen in staat om tegelijkertijd aan een enkel project te werken, waarbij ieder zijn eigen kopie van de code onderhoudt en kiest wanneer deze met de rest van het team wordt gedeeld. Om dit te bereiken, maken ontwikkelaars gebruik van Git-repositories om te helpen met versiebeheer. GitLab is een webgebaseerde Git-repository die meer is dan een tool voor versiebeheer. Het biedt daarnaast DevOps-tools, issue-tracking, continue integratie en implementatie.

GitLab biedt drie opties waaruit u kunt kiezen: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) en GitLab SaaS. GitLab CE and GitLab EE zijn zelfbeheerde oplossingen. Dit betekent dat u de GitLab-instantie zelf kunt downloaden, installeren en beheren. GitLab SaaS wordt gehost door GitLab Inc. U hoeft zich dus geen zorgen te maken over het installeren van wat dan ook om het te gebruiken. U hoeft alleen maar een GitLab-account aan te maken en aan de slag te gaan.

In deze handleiding laten we u zien hoe u Continuous Integration-pipelines opzet met GitLab CI om uw repositories te controleren op wijzigingen en geautomatiseerde tests uit te voeren om nieuwe code te valideren. We beginnen met het opzetten van een Git-repository om de code te hosten. Vervolgens configureren we een CI-proces om commits in de repository te monitoren en starten we een CI-runner om de tests uit te voeren in een geïsoleerde Docker-container.

Vereisten

Om te beginnen heeft u een server nodig waarop de GitLab-versiebeheersoftware draait. Zowel de zelfbeheerde versie van GitLab als de SaaS-versie kunnen geautomatiseerde tests uitvoeren. Er zijn echter enkele limieten wat betreft het aantal minuten en de resources die beschikbaar worden gesteld voor uw tests in de gratis SaaS-opties. U heeft meer vrijheid als u de zelfbeheerde opties gebruikt, omdat u zoveel resources aan uw GitLab-instantie kunt toewijzen als u wilt. Volg onze handleiding over het hosten van uw eigen Git-repositories met GitLab om te leren hoe u uw eigen GitLab-instantie opzet.

U heeft minimaal één server nodig om te gebruiken als GitLab CI-runner. Als u wilt, kunt u echter ook meer servers hebben. Als u een zelfbeheerde GitLab-instantie heeft opgezet, kunt u dezelfde server gebruiken, maar we geven er de voorkeur aan om een andere server in te stellen voor de CI-runner. Deze handleiding over Het instellen van uw Ubuntu-server is een goed begin.

U moet Docker hebben geïnstalleerd op uw GitLab CI-runner-servers om de testomgevingen in Docker-containers te isoleren. We hebben een handleiding over Het installeren en gebruiken van Docker op Ubuntu die u kan helpen om aan deze vereiste te voldoen.

Nu we alles hebben wat we nodig hebben, gaan we aan de slag!

Step 1: Create a Project on a GitLab Instance

We beginnen met het maken van een projectrepository op GitLab. We baseren deze handleiding op een Node.js-applicatie. Omdat we de projectbestanden niet helemaal opnieuw willen maken, biedt GitLab een tool om projecten te importeren uit andere versiebeheer-repositories waar we gebruik van zullen maken. De applicatie die we importeren is een eenvoudige “hello world”-app gebouwd met Express.js – een minimalistisch webframework voor Node.js-applicaties. We zullen de tests implementeren met behulp van Mocha en Chai – dit zijn JavaScript-frameworks die worden gebruikt voor unit-testing. Mocha maakt asynchroon testen en testdekkingsrapporten mogelijk, en kan worden gecombineerd met andere assertion-bibliotheken. Chai is een assertion-bibliotheek. Het kan worden gecombineerd met elk testframework; in ons geval combineren we Mocha met Chai.

Nu u de basis van ons project kent, logt u in op uw GitLab-instantie (zelfbeheerd of SaaS), klikt u op het ‘plus’-pictogram op de bovenste navigatiebalk en selecteert u ‘Nieuw project’. Optioneel kunt u, als u naar de bovenkant van de startpagina van uw account scrollt, op de knop ‘Nieuw project’ klikken:

Klik op de pagina voor een nieuw project op het tabblad Project importeren:

Klik vervolgens op de geopende pagina op de knop Repo by URL button:

Hoewel er een GitHub-importoptie is, gaan we die niet gebruiken omdat deze een persoonlijk toegangstoken (Personal access token) vereist. We hoeven geen persoonlijke toegangstokens in te stellen omdat we met een openbare repository werken, en importeren met alleen de URL is heel eenvoudig.

Kopieer daarna de volgende URL en plak deze in het veld Git Repository URL:

Het zou er zo uit moeten zien:

Laat de repository op Private staan en klik op de knop Create project wanneer je klaar bent. Wacht een paar seconden tot het project is geïmporteerd uit GitHub; het zal dan verschijnen tussen je GitLab-repositories. GitLab importeert het project met dezelfde details als het GitHub-repositoryproject.

Step 2: Analyzing the .gitlab-ci.yml File

GitLab CI scant elke repository op GitLab op een bestand genaamd .gitlab-ci.yml om te weten hoe het geautomatiseerde tests moet uitvoeren. In de repository die we zojuist hebben geïmporteerd, zie je een .gitlab-ci.yml bestand tussen de projectbestanden. Je kunt meer informatie vinden over de GitLab CI yml op hun officiële Keyword-referentie voor de .gitlab-ci.yml-bestandsdocumentatie.

Klik in de GitLab-repository-interface op het .gitlab-ci.yml bestand om het in de browserpagina te openen. Het zou er zo uit moeten zien:

Let op de inspringing van de regels. Het bestand volgt een strikte GitLab CI YAML configuratiesyntaxis om de verschillende uit te voeren acties te definiëren, in een specifieke volgorde onder bepaalde voorwaarden. Om ervoor te zorgen dat je configuratiebestanden correct zijn, biedt GitLab een testhulpprogramma voor validatie. Binnen je GitLab-instantie, in je projectrepository, kun je de CI-lint-interface bezoeken om je .gitlab-ci.yml te valideren. Klik op CI/CD in het linkernavigatiemenu en klik op de knop CI lint op de pagina die verschijnt:

De richtlijnen in het configuratiebestand worden hieronder besproken.

• Basis Docker-image

De eerste regel in het configuratiebestand declareert een Docker-image die moet worden gebruikt om de tests uit te voeren. Omdat we een Node.js-applicatie bouwen, kiezen we voor de nieuwste Node.js-image:

• Stages

Vervolgens definiëren we de verschillende fasen (stages) die onze continuous integration-tests moeten doorlopen. We hebben slechts twee fasen:

Bij het definiëren van de fasenamen zijn namen zoals build of test willekeurig gekozen – je kunt elke gewenste naam kiezen. Je moet de fasen echter wel in de juiste volgorde zetten, omdat dat de uitvoeringsstroom bepaalt. In ons geval worden de taken in de build-fase uitgevoerd vóór de taken in de test-fase. GitLab Runner voert taken in dezelfde fase parallel uit en wacht tot alle taken zijn voltooid voordat hij begint met het uitvoeren van taken in de volgende fase.

• Cache

Een cache-definitie is opgenomen om de bestanden en mappen te specificeren die worden gecached of opgeslagen voor later gebruik tussen de taakuitvoeringen:

Het definiëren van caching helpt de tijd te minimaliseren die nodig is om taken uit te voeren die afhankelijk zijn van bronnen die waarschijnlijk niet veranderen tussen de uitvoeringen. We specificeren de map node_modules om te worden gecached. Dit is de map waarin npm de afhankelijkheden voor het project installeert.

• Jobs

We hebben twee jobs in de configuratie:

• install_dependencies

Bij het benoemen van jobs ben je vrij om elke naam te kiezen. Het is echter aan te raden om een beschrijvende naam te kiezen, aangezien deze in de GitLab-UI worden gebruikt – dit kan handig zijn bij het debuggen. Je zult de meeste configuraties op internet vinden die npm install met de commando's in de testfase. We hebben ze alleen gescheiden om te laten zien hoe taken op elkaar inwerken, aangezien dit een vrij klein project is. De stage-instructie markeert deze taak als build – deze wordt uitgevoerd in de build-stage.

De script-instructie specificeert de commando's die moeten worden uitgevoerd tijdens de uitvoering van deze taak. Je kunt meerdere commando's opgeven door regels toe te voegen binnen het script-blok. Natuurlijk moet je voorzichtig zijn met het correct inspringen en rekening houden met de volgorde waarin de scripts moeten worden uitgevoerd.

De artifacts-instructie specificeert bestanden of mappaden die moeten worden opgeslagen en gedeeld tussen stages. Nogmaals een herinnering dat het correct ordenen van de stages cruciaal is om ervoor te zorgen dat andere bestanden hebben wat ze nodig hebben om te worden uitgevoerd. De npm install-opdracht installeert de afhankelijkheden in de node_modules-map. Door dit in de artifacts te declareren, maken we het beschikbaar voor taken die in volgende stages worden uitgevoerd. De bestanden worden ook beschikbaar gemaakt in de GitLab-UI als je ze wilt downloaden.

• test_with_mocha

Deze taak wordt uitgevoerd in de test-stage. Omdat deze taak wordt uitgevoerd nadat de taak in de build-stage is uitgevoerd, zijn de artifacts die zijn gedeclareerd in de build-stage (dit zijn de afhankelijkheden voor onze app) beschikbaar voor de test-stage. Het scriptblok specificeert de npm-commando's om onze tests uit te voeren. We starten eerst onze applicatie en voeren vervolgens de tests uit op de applicatie. Het uitvoeren van deze commando's activeert de commando's die zijn gespecificeerd in de package.json scriptblok-sectie:
Hiermee zou je een basisbegrip moeten hebben van het .gitlab-ci.yml-bestand. We zeggen basis, omdat dit slechts een statische hello world-app is. Laten we nu kijken hoe we een nieuwe CI-run kunnen activeren.

Step 3: Een GitLab CI-run activeren

Je zult blij zijn te horen dat zodra je repository het .gitlab-ci.yml-bestand bevat, elke nieuwe commit die je ernaartoe pusht een nieuwe Continuous Integration-run zal activeren. In het geval van zelfbeheerde GitLab-instanties zal de CI-run op 'in afwachting' (pending) worden gezet als je geen GitLab-runner hebt geconfigureerd.

GitLab SaaS biedt gebruikers een aantal gedeelde runners die hun taken kunnen oppakken en automatisch kunnen uitvoeren. Dit is alleen mogelijk als de gedeelde runners vrij zijn en je je quotum niet hebt overschreden. In GitLab SaaS kun je kiezen of je wilt dat je repository de shared runners gebruikt of niet door naar de pagina Settings > CI / CD van je project te gaan, zoals getoond in de onderstaande schermafbeelding. Op deze pagina vind je ook informatie over de installatie-instructies voor de GitLab-runner, waar we in de volgende stap dieper op in zullen gaan:

Laten we nu een kleine wijziging aanbrengen om een CI-run te activeren. Navigeer terug naar je node_pipeline GitLab-projectrepository:

Klik op het hierboven gemarkeerde README.md-bestand om het te bekijken:

Klik op de knop ‘Edit’ om het bestand te openen voor bewerking in de browser, en voeg wat tekst toe:

Zodra je wat tekst hebt toegevoegd, scrol je naar beneden en klik je op de knop Commit changes om de wijzigingen op te slaan. Je kunt het commit-bericht naar wens aanpassen. Dit verschijnt als titel in de GitLab-UI wanneer de pipeline wordt uitgevoerd. We hebben het gelaten als Update README.md omdat dit vrij beschrijvend is:

Zodra je de wijzigingen hebt gecommit, keer je terug naar de hoofdpagina van het project. Je zult een klein paused icon zien bij de meest recente commit. Als je met de muis over het icoontje beweegt, wordt er weergegeven: ‘Pipeline:pending’:

Dit betekent dat de CI-run is geactiveerd. De tests zijn echter nog niet uitgevoerd. Klik in het navigatiemenu aan de linkerkant op CI/CD, en selecteer vervolgens Pipelines. Dit opent een pagina met meer details over de pipeline. Je kunt zien dat de CI in afwachting is en als vastgelopen (stuck) is gemarkeerd:

Om meer details over de run te krijgen, klik je op de status pending. Je ziet dan de onderstaande weergave, waarin de verschillende stages van de run en de individuele taken die aan elke stage zijn gekoppeld, worden getoond:

Je kunt ook op individuele taken klikken om de details ervan te bekijken, zoals wat de vertragingen veroorzaakt. In het geval van mislukte runs is dit de plek waar je ziet wat de taak heeft doen mislukken:

Het bericht geeft aan dat de taak vastloopt omdat je geen actieve runners hebt geconfigureerd die deze taak kunnen uitvoeren. Dat gaan we in de volgende stap doen. Wanneer je een runner beschikbaar maakt, begint de taak automatisch met uitvoeren. Wanneer een taak wordt uitgevoerd, zie je de uitvoer op deze interface, evenals de andere downloadbare artefacten die zijn gegenereerd toen de taak werd uitgevoerd.

Stap 4: Een GitLab CI Runner-service instellen

Het is nu tijd om gebruik te maken van de tweede server die we hebben gedeclareerd in de sectie Vereisten van deze handleiding. We gaan een GitLab runner-service installeren en instellen op deze server. Je kunt de service implementeren om meerdere runner-instanties uit te voeren voor verschillende projecten op GitLab.

Je hebt de optie om de runner te implementeren op dezelfde server die je zelfbeheerde GitLab-instantie host. Om er echter zeker van te zijn dat een instantie niet wordt beperkt door resources, is het de voorkeur om een aparte CI-runner-instantie in te stellen. Welke configuratie je ook kiest, Docker moet geïnstalleerd zijn om de testomgevingen te isoleren.

Het proces voor het installeren van de GitLab CI-runner is vergelijkbaar met dat voor het installeren van de zelfbeheerde GitLab-instantie. We beginnen met het downloaden van een script om de officiële GitLab-repository toe te voegen aan de apt-bronnen met behulp van de volgende opdracht:

Voer je root-wachtwoord in wanneer daarom wordt gevraagd. Vervolgens kun je de opdracht uitvoeren om de nieuwste GitLab CI-runner te installeren:

De bovenstaande opdracht installeert en registreert een runner-service die klaar is voor gebruik door je projecten.

Stap 5: Registratietokens verkrijgen en de GitLab-runner koppelen

Om een GitLab CI-runner in te stellen zodat deze taken kan accepteren, heb je een GitLab-runnertoken nodig. Dit is nodig voor de runner om te authenticeren bij je GitLab-serverinstantie. Er zijn twee soorten tokens, afhankelijk van hoe je de runner wilt gebruiken: projectspecifiek en gedeelde runner.

Projectspecifieke runners zijn van toepassing als je unieke vereisten hebt voor de runner. Als je bijvoorbeeld implementatiedefinities hebt in je gitlab-ci.yml met unieke tokens, dan kan een specifieke runner worden aanbevolen om correct te authenticeren in de implementatieomgeving. Een andere overweging is of je continue integratiefasen resource-intensieve processen hebben. Dan zou het ideaal zijn om te kiezen voor een projectspecifieke runner. Let op: een projectspecifieke runner accepteert geen taken van andere projecten.

Gedeelde runners zijn voor algemeen gebruik en kunnen door meerdere projecten worden gebruikt. De GitLab SaaS-instantie gehost op GitLab Inc heeft een aantal gedeelde runners die automatisch je pipelines oppakken, zoals uitgelegd in Stap drie. Runners nemen taken over van je configuraties op basis van een algoritme dat rekening houdt met het aantal taken dat momenteel voor elk project wordt uitgevoerd. Een gedeelde runner is flexibeler dan een specifieke runner. Deze kan worden geconfigureerd vanuit het beheerdersaccount van de GitLab-instantie. Laten we eens kijken hoe we de tokens voor beide runners kunnen verkrijgen.

• Een projectspecifieke runner registreren

Om een projectspecifieke runner te registreren, open je je project in je GitLab-instantie of GitLab SaaS-account. Klik in het navigatiemenu aan de linkerkant op het item Instellingen en selecteer de CI/CD optie:

Scroll daarna naar beneden naar de sectie Runners en klik op de knop om de sectie uit te vouwen:

De linkerkant legt uit hoe je een projectspecifieke runner registreert. Dit is een weergave van de GitLab SaaS-instantie. Je kunt ook automatische runners configureren met Kubernetes, maar voor deze handleiding gebruiken we de handmatige runner:

Vervolgens moet je je richten op het gedeelte waar je de token voor dit project krijgt. Voor een zelfbeheerde GitLab-instantie toont de URL het domein van de server waarop je GitLab-instantie draait:

Je kunt ervoor kiezen om gedeelde runners voor dit project uit te schakelen door de schakelaar aan de rechterkant om te zetten onder Gedeelde runners. Kopieer vervolgens de weergegeven registratietoken naar je kladblok, want die hebben we later nodig.

• Een gedeelde runner registreren

Om een gedeelde runner te registreren, moet je als beheerder inloggen op je zelfbeheerde GitLab-instantie. Om toegang te krijgen tot het beheerderspaneel, klik je op het moersleutel-icoon in het bovenste navigatiemenu:

In het Beheerderspaneel, klik op Runners in de sectie Overzicht van het linkermenu. Dit opent een pagina met de Gedeelde runners-configuratie-instructies:

Kopieer de registratietoken die aan de rechterkant wordt weergegeven onder Handmatig een gedeelde Runner instellen. Je gebruikt de token om de runner in de volgende stap te registreren.

• Een GitLab CI-runner koppelen aan een GitLab-instantie

In deze stap koppel je je GitLab-instantie aan de CI-runner. Log opnieuw in op de server waarop je de GitLab-runner-service hebt geïnstalleerd in Stap vier. Om het registratieproces van de runner te starten, voer je de volgende opdracht in je terminal in:

De opdracht stelt je een reeks vragen:

• Voer de URL van de GitLab-instantie in (bijvoorbeeld https://gitlab.com/):

Geef de domeinnaam van je GitLab-instantie op met https:// om SSL te specificeren.

• Voer de registratietoken in:

Geef je registratietoken op. Hier kies je of je wilt dat deze runner projectspecifiek of gedeeld is. Je kunt voor beide opties slechts één van de eerder gekopieerde tokens opgeven.

• Voer een beschrijving in voor de runner:

Kies een beschrijvende naam voor je CI-runner zoals deze in de gebruikersinterface van de GitLab-instantie zal verschijnen.

• Voer een executor in: custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Hier krijg je opties om een executor te kiezen om de taken uit te voeren. Voer Docker.

• Voer tags in voor de runner (komma-gescheiden):

Dit is optioneel. Je kunt eventuele tagnamen invoeren, zoals afhankelijkheden die deze runner bevat. Je kunt dit voorlopig leeg laten.

• Voer de standaard Docker-image in (bijvoorbeeld ruby:2.6):

Hier wordt van je verwacht dat je een standaard image voor algemeen gebruik opgeeft die wordt gebruikt om taken uit te voeren voor het geval het gitlab-ci.yml-bestand geen image specificeert. Voer alpine:latest in, aangezien dit een kleine, veilige image voor algemeen gebruik is. Druk op enter en de runner wordt automatisch geregistreerd en gestart:

Om de lijst met momenteel beschikbare runners te bekijken, voer je de volgende opdracht in:

Stap 6: Bevestigen dat de CI-runner succesvol is gekoppeld in GitLab

Keer vervolgens terug naar je browser en bezoek je projectpagina in de GitLab-instantie. Afhankelijk van hoeveel minuten er zijn verstreken sinds je de runner hebt geregistreerd, zie je mogelijk dat de taak momenteel wordt uitgevoerd:

Of deze is mogelijk al voltooid:

Navigeer daarna naar de pagina Pipelines via het linkermenu CI/CD > Pipelines, of door te klikken op het running, passed, of failed-icoon (als de pijplijn fouten heeft aangetroffen) om de status van de CI-run te bekijken. Hier kunnen we zien dat een van de fasen (build-fase) is geslaagd, terwijl er nog een actief is:

Klik in de tabel, onder de kop Stages, op een van de fase-iconen om de bijbehorende taken te bekijken:

Klik vervolgens op een taak in de pop-up om de details te bekijken:

De taak is uitgevoerd en je kunt de voortgang zien wanneer de opdracht npm de afhankelijkheden aan het installeren was. Aan de rechterkant kun je andere gerelateerde informatie bekijken. Je hebt de optie om de artefacten van de taak te downloaden. Je kunt ook tussen fasen schakelen om andere taken uit de vervolgkeuzelijst te bekijken.

Hier kun je onze testcases bekijken die laten zien wanneer je de taak in de testfase selecteert:

Beschikbare runners

Als je in het linkermenu klikt op Settings > CI/CD, en vouw Runners uit-sectie. Je zou de runner moeten zien die je zojuist hebt geregistreerd. Afhankelijk van of je een projectspecifieke token of een gedeelde token had opgegeven, verschijnt de runner respectievelijk in de betreffende sectie.

Hier kun je zien dat we een projectspecifieke token hebben geregistreerd. De runner verschijnt onder de Specifieke runners:

Conclusie

In deze handleiding heb je geleerd hoe je je tests kunt automatiseren met GitLab CI. We zijn begonnen met het opzetten van een Node.js-app-project op GitLab. Het project bevatte enkele testcases en een gitlab-ci.yml-bestand. We hebben geleerd dat GitLab het gitlab-ci.yml-bestand gebruikt om te bepalen wat er moet gebeuren als het wordt geactiveerd. Een gitlab-ci.yml-bestand is gewoon een configuratiebestand dat instructies bevat voor het bouwen en testen van applicaties, geschreven in de YAML-indeling die een GitLab CI-runner kan begrijpen.

We zijn er ook in geslaagd om een GitLab CI-runner op een aparte host op te zetten. We hebben deze geregistreerd om taken van onze GitLab-instanties aan te nemen wanneer er een trigger is. Hoewel dit een eenvoudig project was, kun je op basis van deze informatie pipelines opzetten voor complexe projecten. De stappen voor het toevoegen van een project aan GitLab en het koppelen van een GitLab CI-runner blijven hetzelfde. Wat verandert zijn de instructies en fasen in het gitlab-ci.yml-bestand.

Veel computerplezier!