Come configurare le pipeline di Continuous Integration (CI) di GitLab su Ubuntu 20.04

Ogni sviluppatore comprende quanto il controllo di versione sia fondamentale per il ciclo di vita dello sviluppo del software. Consente a più persone di lavorare contemporaneamente su un singolo progetto, mantenendo ciascuna la propria copia del codice e scegliendo quando condividerla con il resto del team. Per ottenere questo, gli sviluppatori utilizzano Git repository per facilitare il controllo di versione. GitLab è un repository Git basato sul web che è molto più di uno strumento di controllo di versione. Fornisce inoltre strumenti DevOps, tracciamento dei problemi, integrazione continua e distribuzione.

GitLab offre tre opzioni tra cui scegliere: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) e GitLab SaaS. GitLab CE e GitLab EE sono soluzioni autogestite. Ciò significa che spetta a te scaricare, installare e gestire l'istanza di GitLab. GitLab SaaS è ospitato da GitLab Inc. Pertanto, non devi preoccuparti di installare nulla per utilizzarlo. Devi solo creare un account GitLab e iniziare.

In questo tutorial, ti mostreremo come configurare pipeline di Continuous Integration con GitLab CI per monitorare i tuoi repository alla ricerca di modifiche ed eseguire test automatizzati per convalidare il nuovo codice. Inizieremo configurando un repository Git per ospitare il codice. Successivamente, configureremo un processo di CI per monitorare i commit nel repository e avvieremo un runner CI per eseguire i test in un container Docker isolato.

Prerequisiti

Per iniziare, avrai bisogno di un server su cui è in esecuzione il software di controllo di versione GitLab. Sia GitLab autogestito che SaaS possono eseguire test automatizzati. Tuttavia, ci sono alcuni limiti in termini di minuti e risorse messe a disposizione per i tuoi test nelle opzioni SaaS gratuite. Hai maggiore libertà se utilizzi le opzioni autogestite perché puoi allocare quante risorse desideri alla tua istanza GitLab. Segui il nostro tutorial su ospitare i tuoi repository Git con GitLab per imparare a configurare la tua istanza GitLab.

Avrai bisogno di almeno un server da utilizzare come runner GitLab CI. Tuttavia, se desideri, puoi avere anche più server. Se hai configurato un'istanza GitLab autogestita, puoi utilizzare lo stesso server, ma preferiamo configurare un server diverso per il runner CI. Questo tutorial su Come configurare il tuo server Ubuntu è un buon inizio.

Avrai bisogno di Docker installato sui tuoi server runner GitLab CI per isolare gli ambienti di test in container Docker. Abbiamo un tutorial su Come installare e utilizzare Docker su Ubuntu che può aiutarti a completare questo requisito.

Ora che abbiamo tutto il necessario, iniziamo!

Passaggio 1: Creare un progetto su un'istanza GitLab

Inizieremo creando un repository di progetto su GitLab. Baseremo questo tutorial su un' applicazione Node.js. Poiché non vogliamo creare i file di progetto da zero, GitLab offre uno strumento per importare progetti da altri repository di controllo di versione di cui usufruiremo. L'applicazione che stiamo importando è una semplice app “hello world” realizzata con Express.js – un framework web minimalista per applicazioni Node.js. Implementeremo i test utilizzando Mocha e Chai – questi sono framework JavaScript utilizzati per gli unit test. Mocha consente test asincroni, report sulla copertura dei test e può essere associato ad altre librerie di asserzione. Chai è una libreria di asserzione. Può essere associata a qualsiasi framework di test; nel nostro caso, assoceremo Mocha con Chai.

Ora che conosci le basi del nostro progetto, accedi alla tua istanza GitLab (sia essa autogestita o SaaS), fai clic sull'icona ‘più’ sulla barra di navigazione superiore e seleziona ‘Nuovo progetto’. In alternativa, se scorri fino alla parte superiore della homepage del tuo account, puoi fare clic sul pulsante ‘Nuovo progetto’:

Nella pagina del nuovo progetto, fai clic sulla scheda Importa progetto :

Successivamente, nella pagina aperta, fai clic sul pulsante Repo tramite URL :

Sebbene sia presente un'opzione di importazione da GitHub, non la utilizzeremo poiché richiede un token di accesso personale. Non abbiamo bisogno di configurare token di accesso personali poiché stiamo lavorando con un repository pubblico, e l'importazione con il solo URL è semplicissima.

Dopodiché, copia il seguente URL e incollalo nel campo URL del repository Git:

Dovrebbe apparire così:

Lascia il repository come Privato e fai clic sul pulsante Create project quando hai finito. Attendi un paio di secondi affinché il progetto venga importato da GitHub; apparirà tra i tuoi repository GitLab. GitLab importa il progetto con gli stessi dettagli del progetto del repository GitHub.

Passo 2: Analisi del file .gitlab-ci.yml

GitLab CI esegue la scansione di ogni repository su GitLab alla ricerca di un file chiamato .gitlab-ci.yml per sapere come eseguire i test automatizzati. Nel repository che abbiamo appena importato, puoi vedere un file .gitlab-ci.yml tra i file del progetto. Puoi trovare maggiori informazioni sul file yml di GitLab CI sulla loro documentazione ufficiale Riferimento delle parole chiave per il file .gitlab-ci.yml.

Mentre ti trovi nell'interfaccia del repository GitLab, fai clic sul file .gitlab-ci.yml per aprirlo nella pagina del browser. Dovrebbe apparire così:

Nota l'indentazione delle righe. Il file segue una rigida GitLab CI YAML sintassi di configurazione per definire le varie azioni da intraprendere, in un ordine specificato e a determinate condizioni. Per garantire che i file di configurazione siano corretti, GitLab fornisce un'utilità di test per la convalida. All'interno della tua istanza GitLab, nel repository del tuo progetto, puoi visitare l'interfaccia CI lint per convalidare il tuo .gitlab-ci.yml. Fai clic su CI/CD nel menu di navigazione a sinistra e fai clic sul pulsante CI lint nella pagina che appare:

Le direttive nel file di configurazione sono discusse di seguito.

• Immagine Docker di base

La prima riga nel file di configurazione dichiara un'immagine Docker che dovrebbe essere utilizzata per eseguire i test. Poiché stiamo creando un'applicazione Node.js, utilizzeremo l'immagine Node.js più recente:

• Stage

Quindi, definiamo i diversi stage che vogliamo vengano superati dai nostri test di integrazione continua. Abbiamo solo due stage:

Durante la definizione dei nomi degli stage, nomi come build o test sono scelti arbitrariamente – puoi scegliere qualsiasi nome desideri. Tuttavia, devi ordinare correttamente gli stage perché ciò determina il flusso di esecuzione. Nel nostro caso, i job nello stage build vengono eseguiti prima dei job nello stage test . GitLab runner eseguirà i job nello stesso stage in parallelo e attenderà il completamento di tutti i job prima di iniziare a eseguire i job dello stage successivo.

• Cache

Una cache definizione è inclusa per specificare i file e le directory che verranno memorizzati nella cache o salvati per un uso successivo tra le esecuzioni dei job:

La definizione della memorizzazione nella cache aiuta a ridurre al minimo il tempo necessario per eseguire i job che si affidano a risorse che difficilmente cambieranno tra un'esecuzione e l'altra. Specifichiamo la directory node_modules da memorizzare nella cache. Questa è la directory in cui npm installa le dipendenze per il progetto.

• Job

Abbiamo due job nella configurazione:

• install_dependencies

Quando assegni un nome ai job, sei libero di scegliere qualsiasi nome. Tuttavia, si consiglia di utilizzare un nome descrittivo poiché vengono utilizzati nell'interfaccia utente di GitLab – questo può essere utile durante il debug. Troverai la maggior parte delle configurazioni sul web che combinano npm install con i comandi nella fase di test. Li abbiamo separati solo per aiutare a dimostrare come interagiscono i job, dato che si tratta di un progetto piuttosto piccolo. Il stage la direttiva contrassegna questo job come build – viene eseguito nella build stage.

La direttiva script specifica i comandi da eseguire nell'esecuzione di questo job. È possibile specificare più comandi aggiungendo righe all'interno del blocco script. Naturalmente, è necessario fare attenzione a rientrare correttamente e a tenere presente l'ordine in cui gli script devono essere eseguiti.

La direttiva artifacts specifica i file o i percorsi delle directory da salvare e condividere tra i vari stage. Ancora una volta, ricordiamo che ordinare correttamente gli stage è fondamentale per garantire che gli altri file abbiano ciò di cui hanno bisogno per l'esecuzione. Il comando npm install installerà le dipendenze nella directory node_modules directory. Dichiarandolo negli artifacts, lo rendiamo disponibile per i job eseguiti negli stage successivi. I file sono resi disponibili anche nell'interfaccia utente di GitLab se desideri scaricarli.

• test_with_mocha

Questo job viene eseguito sullo test stage. Poiché questo job viene eseguito dopo che il job nello build stage è stato eseguito, gli artifacts dichiarati nello build stage (che sono le dipendenze per la nostra app) saranno disponibili per lo test stage. Il blocco script specifica i comandi npm per eseguire i nostri test. Prima avviamo la nostra applicazione e poi eseguiamo i test su di essa. L'esecuzione di questi comandi avvia i comandi specificati nella sezione del blocco script di package.json:
Con questo, dovresti avere una comprensione di base del file .gitlab-ci.yml. Diciamo di base perché questa è solo un'app statica hello world app. Successivamente, vediamo come attivare una nuova esecuzione di CI.

Step 3: Triggering a GitLab CI Run

Sarai felice di sapere che una volta che il tuo repository ha il file .gitlab-ci.yml, qualsiasi nuovo commit di cui farai il push attiverà una nuova esecuzione di Continuous Integration. Nel caso di istanze GitLab autogestite, se non hai configurato un GitLab runner, l'esecuzione di CI sarà impostata su “pending”.

GitLab SaaS offre agli utenti alcuni runner condivisi in grado di prendere in carico i loro job ed eseguirli automaticamente. Questo è possibile solo se i runner condivisi sono liberi e non hai superato la tua quota. In GitLab SaaS, puoi scegliere se desideri che il tuo repository utilizzi i shared runners o meno andando alla pagina Settings > CI / CD del tuo progetto, come mostrato nello screenshot qui sotto. In questa pagina troverai anche informazioni sulle istruzioni di installazione del runner di GitLab, che approfondiremo nel prossimo passo:

Ora, apportiamo una piccola modifica per attivare un'esecuzione di CI. Torna al repository del tuo progetto GitLab node_pipeline:

Fai clic sul file README.md evidenziato sopra per visualizzarlo:

Fai clic sul pulsante ‘Edit’ per aprire il file per la modifica nel browser e aggiungi del testo:

Dopo aver aggiunto del testo, scorri verso il basso e fai clic sul pulsante Commit changes per salvare le modifiche. Puoi modificare il messaggio di commit come desideri. Apparirà come titolo nell'interfaccia utente di GitLab quando la pipeline è in esecuzione. Lo abbiamo lasciato come Update README.md in quanto è piuttosto descrittivo:

Dopo aver eseguito il commit delle modifiche, torna alla pagina principale del progetto. Noterai una piccola icona di pausa associata al commit più recente. Se passi il mouse sopra l'icona, verrà visualizzato: ‘Pipeline:pending’:

Ciò significa che l'esecuzione di CI è stata attivata. Tuttavia, i test non sono ancora stati eseguiti. Nel menu di navigazione a sinistra, fai clic su CI/CD, quindi seleziona Pipelines. Questo aprirà una pagina che mostra maggiori dettagli sulla pipeline. Puoi vedere che la CI è in sospeso e contrassegnata come bloccata:

Per ottenere maggiori dettagli sull'esecuzione, fai clic sullo stato pending. Vedrai la schermata qui sotto, che mostra i diversi stage dell'esecuzione e i singoli job collegati a ciascuno stage:

Puoi anche fare clic sui singoli job per vederne i dettagli più precisi, come ad esempio cosa sta causando i ritardi. Nel caso di esecuzioni fallite, qui è dove vedrai cosa ha causato il fallimento del job:

Il messaggio indica che il job è bloccato perché non hai configurato alcun runner attivo in grado di eseguirlo. Lo faremo nel passaggio successivo. Quando renderai disponibile un runner, il job inizierà a essere eseguito automaticamente. Quando un job viene eseguito, vedrai l'output su questa interfaccia, oltre agli altri artefatti scaricabili generati durante l'esecuzione del job.

Passaggio 4: Configurazione di un servizio GitLab CI Runner

È giunto il momento di utilizzare il secondo server che abbiamo dichiarato nella sezione Prerequisiti di questo tutorial. Installeremo e configureremo un servizio GitLab runner su questo server. Puoi distribuire il servizio per eseguire più istanze di runner per diversi progetti su GitLab.

Hai la possibilità di distribuire il runner sullo stesso server che ospita la tua istanza GitLab self-managed. Tuttavia, per garantire che un'istanza non sia limitata dalle risorse, è preferibile configurare un'istanza di CI runner separata. Qualunque sia la configurazione scelta, Docker deve essere installato per isolare gli ambienti di test.

Il processo di installazione di GitLab CI runner è paragonabile a quello per l'installazione dell'istanza GitLab self-managed . Iniziamo scaricando uno script per aggiungere il repository ufficiale di GitLab ai sorgenti apt utilizzando il seguente comando:

Fornisci la tua password di root quando richiesto. Successivamente, puoi eseguire il comando per installare l'ultimo GitLab CI runner:

Il comando precedente installa e registra un servizio runner pronto per essere utilizzato dai tuoi progetti.

Passaggio 5: Ottenere i token di registrazione e collegare il GitLab Runner

Per configurare un GitLab CI runner in modo che inizi ad accettare job, hai bisogno di un token di GitLab runner. È necessario affinché il runner si autentichi con la tua istanza del server GitLab. Esistono due tipi di token a seconda di come desideri utilizzare il runner: specifici del progetto e runner condivisi.

I runner specifici del progetto sono applicabili se hai requisiti unici per il runner. Ad esempio, se hai definizioni di deployment nel tuo gitlab-ci.yml con token unici, potrebbe essere consigliato un runner specifico per autenticarsi correttamente nell'ambiente di deployment. Un'altra considerazione riguarda il caso in cui le fasi di integrazione continua presentino processi ad alta intensità di risorse. In tal caso, sarebbe ideale optare per un runner specifico del progetto. Nota che un runner specifico del progetto non accetta job da altri progetti.

I runner condivisi sono di tipo general-purpose e possono essere utilizzati da più progetti. L'istanza GitLab SaaS ospitata su GitLab Inc dispone di alcuni runner condivisi che prenderanno automaticamente in carico le tue pipeline, come spiegato nel Passaggio tre. I runner prendono i job dalle tue configurazioni in base a un algoritmo che tiene conto del numero di job attualmente in esecuzione per ciascun progetto. Un runner condiviso è più flessibile di un runner specifico. Può essere configurato dall'account amministratore dell'istanza GitLab. Vediamo come procedere per ottenere i token per entrambi i runner.

• Registrazione di un runner specifico del progetto

Per registrare un runner specifico del progetto, apri il tuo progetto nella tua istanza GitLab o nel tuo account GitLab SaaS. Dal menu di navigazione a sinistra, fai clic sulla voce Impostazioni e seleziona l'opzione CI/CD:

Dopodiché, scorri verso il basso fino alla sezione Runners e fai clic sul pulsante per espandere la sezione:

La parte sinistra spiega come registrare un runner specifico del progetto. Questa è una visualizzazione dell'istanza GitLab SaaS. Puoi anche configurare runner automatici con Kubernetes, ma in questo tutorial utilizzeremo il runner manuale:

Successivamente, devi concentrarti sulla sezione in cui ti viene fornito il token per questo progetto. Per un'istanza GitLab self-managed, l'URL mostrerà il dominio del server su cui è in esecuzione la tua istanza GitLab:

Puoi scegliere di disabilitare i runner condivisi per questo progetto attivando l'interruttore nella sezione a destra sotto Runner condivisi. Quindi, copia il token di registrazione visualizzato nel tuo blocco note, poiché lo useremo più tardi.

• Registrazione di un Runner Condiviso

Per registrare un runner condiviso, devi accedere alla tua istanza GitLab self-managed come amministratore. Per accedere al pannello di amministrazione, fai clic sull'icona chiave inglese nel menu di navigazione superiore:

Nell'Area Amministrativa, fai clic su Runner nella sezione Panoramica del menu a sinistra. Questo aprirà una pagina con le istruzioni di configurazione dei Runner condivisi:

Copia il token di registrazione visualizzato sul lato destro sotto Configura un Runner condiviso manualmente. Utilizzerai il token per registrare il runner nel passaggio successivo.

• Collegamento di un GitLab CI Runner a un'istanza GitLab

In questo passaggio, collegherai la tua istanza GitLab con il CI runner. Accedi nuovamente al server in cui hai installato il servizio GitLab runner nel Passo Quattro. Per avviare il processo di registrazione del runner, inserisci il seguente comando nel tuo terminale:

Il comando ti porrà una serie di domande:

• Inserisci l'URL dell'istanza GitLab (ad esempio, https://gitlab.com/):

Fornisci il nome di dominio della tua istanza GitLab utilizzando https:// per specificare SSL.

• Inserisci il token di registrazione:

Fornisci il tuo token di registrazione. Qui sceglierai se desideri che questo runner sia specifico per il progetto o condiviso. Puoi fornire solo uno dei token copiati in precedenza per una delle due opzioni.

• Inserisci una descrizione per il runner:

Scegli un nome descrittivo per il tuo CI runner, poiché apparirà nell'interfaccia utente dell'istanza GitLab.

• Inserisci un esecutore: custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Qui ti vengono fornite le opzioni per scegliere un esecutore per eseguire i job. Inserisci Docker.

• Inserisci i tag per il runner (separati da virgole):

Questo è facoltativo. Puoi inserire qualsiasi nome di tag, come le dipendenze incluse in questo runner. Per ora puoi lasciarlo vuoto.

• Inserisci l'immagine Docker predefinita (ad esempio, ruby:2.6):

Qui dovresti specificare un'immagine generica predefinita utilizzata per eseguire i job nel caso in cui il file gitlab-ci.yml non specifichi un'immagine. Inserisci alpine:latest poiché si tratta di un'immagine piccola, generica e sicura. Premi invio e il runner verrà registrato e avviato automaticamente:

Per visualizzare l'elenco dei runner attualmente disponibili, inserisci il seguente comando:

Passaggio 6: Conferma del corretto collegamento del CI Runner in GitLab

Successivamente, torna al browser e visita la pagina del tuo progetto nell'istanza GitLab. A seconda di quanti minuti sono passati da quando hai registrato il runner, potresti vedere che il job è attualmente in esecuzione:

O potrebbe essere stato completato:

Dopodiché, naviga alla pagina Pipeline sia tramite il menu a sinistra CI/CD > Pipelines, sia facendo clic sull'icona running, passed, o failed (se la pipeline ha riscontrato errori) per visualizzare lo stato dell'esecuzione CI. Qui possiamo vedere che una delle fasi (fase di build) è stata superata, mentre una è ancora in esecuzione:

Nella tabella, sotto l'intestazione Stage, fai clic su una delle icone degli stage per visualizzare i job associati:

Quindi, fai clic su un job nel pop-up per visualizzarne i dettagli:

Il job è stato eseguito e puoi vedere l'avanzamento di quando il comando npm stava installando le dipendenze. Sul lato destro, puoi visualizzare altre informazioni correlate. Hai la possibilità di scaricare gli artefatti dal job. Puoi anche passare da una fase all'altra per visualizzare altri job dal menu a discesa.

Qui puoi visualizzare i nostri casi di test che mostrano quando selezioni il job nella fase di test:

Runner Disponibili

Nel menu a sinistra, se fai clic su Impostazioni > CI/CD, ed espandi la sezione Runner sezione, dovresti vedere il runner che hai appena registrato. A seconda che tu abbia specificato un token specifico per il progetto o un token condiviso, il runner apparirà rispettivamente in una delle due sezioni.

Qui puoi vedere che abbiamo registrato un token specifico per il progetto. Un runner appare sotto Runner specifici:

Conclusione

In questo tutorial, hai imparato come automatizzare i tuoi test con GitLab CI. Abbiamo iniziato configurando un progetto di app Node.js su GitLab. Il progetto includeva alcuni casi di test e un gitlab-ci.yml. Abbiamo imparato che GitLab utilizza il gitlab-ci.yml file per determinare cosa fare quando viene attivato. Un gitlab-ci.yml file è solo un file di configurazione che contiene istruzioni su come compilare e testare le applicazioni, scritto in YAML formato che un runner di GitLab CI può comprendere.

Siamo anche riusciti a configurare un runner di GitLab CI su un host separato. Lo abbiamo registrato per accettare i job dalle nostre istanze di GitLab ogni volta che c'è un trigger. Sebbene questo fosse un progetto semplice, puoi basarti su queste informazioni per configurare pipeline per progetti complessi. I passaggi per aggiungere un progetto a GitLab e collegare un runner di GitLab CI rimangono gli stessi. Le cose che cambiano sono le istruzioni e i passaggi nel gitlab-ci.yml file.

Buona programmazione!