Jak skonfigurować potoki GitLab Continuous Integration (CI) na Ubuntu 20.04

Każdy programista rozumie, jak kluczowa dla cyklu życia oprogramowania jest kontrola wersji. Umożliwia ona wielu osobom jednoczesną pracę nad jednym projektem, przy czym każda osoba zachowuje własną kopię kodu i decyduje, kiedy udostępnić ją reszcie zespołu. Aby to osiągnąć, programiści korzystają z Git repozytoriów, które pomagają w kontroli wersji. GitLab to internetowe repozytorium Git, które jest czymś więcej niż tylko narzędziem do kontroli wersji. Zapewnia ponadto narzędzia DevOps, śledzenie problemów, ciągłą integrację i wdrażanie.

GitLab oferuje trzy opcje do wyboru: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) oraz GitLab SaaS. GitLab CE and GitLab EE to rozwiązania samodzielnie zarządzane (self-managed). Oznacza to, że samodzielnie pobierasz, instalujesz i zarządzasz instancją GitLab. GitLab SaaS jest hostowany przez GitLab Inc. Dzięki temu nie musisz się martwić o instalowanie czegokolwiek, aby z niego korzystać. Musisz jedynie utworzyć konto GitLab i zacząć.

W tym samouczku pokażemy Ci, jak skonfigurować potoki ciągłej integracji (Continuous Integration) za pomocą GitLab CI w celu monitorowania repozytoriów pod kątem zmian i uruchamiania automatycznych testów do walidacji nowego kodu. Rozpoczniemy od skonfigurowania repozytorium Git do hostowania kodu. Następnie skonfigurujemy proces CI do monitorowania commitów w repozytorium i uruchomimy runnera CI, aby przeprowadzić testy w odizolowanym kontenerze Docker.

Wymagania wstępne

Na początek będziesz potrzebować serwera z uruchomionym oprogramowaniem do kontroli wersji GitLab. Zarówno GitLab self-managed, jak i SaaS mogą uruchamiać automatyczne testy. Istnieją jednak pewne ograniczenia dotyczące minut i zasobów udostępnianych testom w bezpłatnych opcjach SaaS. Masz większą swobodę, jeśli korzystasz z opcji self-managed, ponieważ możesz przydzielić swojej instancji GitLab tyle zasobów, ile chcesz. Postępuj zgodnie z naszym samouczkiem dotyczącym hostowania własnych repozytoriów Git za pomocą GitLab, aby dowiedzieć się, jak skonfigurować własną instancję GitLab.

Będziesz potrzebować co najmniej jednego serwera, który posłuży jako runner GitLab CI. Jeśli jednak chcesz, możesz mieć również więcej serwerów. Jeśli skonfigurowałeś instancję GitLab self-managed, możesz użyć tego samego serwera, ale my preferujemy skonfigurowanie osobnego serwera dla runnera CI. Ten samouczek dotyczący Jak skonfigurować serwer Ubuntu to dobry początek.

Będziesz potrzebować zainstalowanego Dockera na serwerach runnerów GitLab CI, aby odizolować środowiska testowe w kontenerach Docker. Mamy samouczek dotyczący Jak zainstalować i obsługiwać Dockera na Ubuntu, który pomoże Ci spełnić to wymaganie.

Skoro mamy już wszystko, czego potrzebujemy, zacznijmy!

Krok 1: Utworzenie projektu w instancji GitLab

Zaczniemy od utworzenia repozytorium projektu w GitLabie. Oprzemy ten samouczek na aplikacji Node.js. Ponieważ nie chcemy tworzyć plików projektu od zera, skorzystamy z oferowanego przez GitLab narzędzia do importowania projektów z innych repozytoriów kontroli wersji. Importowana aplikacja to prosta aplikacja „hello world” zbudowana przy użyciu Express.js – minimalistycznego frameworka webowego dla aplikacji Node.js. Testy zaimplementujemy przy użyciu Mocha i Chai – są to frameworki JavaScript używane do testów jednostkowych. Mocha umożliwia testowanie asynchroniczne, raportowanie pokrycia testów i może być łączona z innymi bibliotekami asercji. Chai to biblioteka asercji. Można ją połączyć z dowolnym frameworkiem testowym, w naszym przypadku połączymy Mochę z Chai.

Skoro znasz już podstawy naszego projektu, zaloguj się do swojej instancji GitLab (zarówno self-managed, jak i SaaS), kliknij „plus” na górnym pasku nawigacyjnym i wybierz „New project”. Opcjonalnie, jeśli przewiniesz na samą górę strony głównej swojego konta, możesz kliknąć przycisk „New project”:

Na stronie nowego projektu kliknij Import project zakładkę:

Następnie na otwartej stronie kliknij Repo by URL przycisk:

Choć istnieje opcja importu z GitHub, nie będziemy z niej korzystać, ponieważ wymaga ona osobistego tokenu dostępu (Personal access token). Nie musimy konfigurować osobistych tokenów dostępu, ponieważ pracujemy z repozytorium publicznym, a importowanie za pomocą samego adresu URL jest bardzo proste.

Następnie skopiuj poniższy adres URL i wklej go w pole Git Repository URL:

Powinno to wyglądać tak:

Pozostaw repozytorium jako Private i kliknij przycisk Create project po zakończeniu. Poczekaj kilka sekund na zaimportowanie projektu z GitHub, a pojawi się on wśród Twoich repozytoriów GitLab. GitLab importuje projekt z takimi samymi szczegółami jak projekt w repozytorium GitHub.

Krok 2: Analiza pliku .gitlab-ci.yml

GitLab CI przeszukuje każde repozytorium na GitLab w poszukiwaniu pliku o nazwie .gitlab-ci.yml, aby wiedzieć, jak uruchomić testy automatyczne. W zaimportowanym właśnie repozytorium możesz zobaczyć plik .gitlab-ci.yml wśród plików projektu. Więcej informacji na temat GitLab CI yml można znaleźć w ich oficjalnej dokumentacji Keyword reference for the .gitlab-ci.yml file.

Będąc w interfejsie repozytorium GitLab, kliknij plik .gitlab-ci.yml, aby otworzyć go w oknie przeglądarki. Powinien on wyglądać następująco:

Zwróć uwagę na wcięcia linii. Plik opiera się na ścisłej składni konfiguracji GitLab CI YAML configuration syntax, aby zdefiniować różne działania do podjęcia, w określonej kolejności i pod pewnymi warunkami. Aby upewnić się, że pliki konfiguracyjne są poprawne, GitLab udostępnia narzędzie testowe do walidacji. Wewnątrz swojej instancji GitLab, w repozytorium projektu, możesz odwiedzić interfejs CI lint, aby zweryfikować swój .gitlab-ci.yml. Kliknij CI/CD w lewym menu nawigacyjnym, a następnie kliknij przycisk CI lint na stronie, która się pojawi:

Dyrektywy w pliku konfiguracyjnym zostały omówione poniżej.

• Bazowy obraz Docker

Pierwsza linia w pliku konfiguracyjnym deklaruje obraz Docker, który powinien zostać użyty do uruchomienia testów. Ponieważ budujemy aplikację Node.js, wybieramy najnowszy obraz Node.js:

• Etapy

Następnie definiujemy różne etapy, przez które mają przejść nasze testy ciągłej integracji. Mamy tylko dwa etapy:

Podczas definiowania nazw etapów, nazwy takie jak build lub test są wybierane losowo – możesz wybrać dowolną nazwę. Musisz jednak odpowiednio uporządkować etapy, ponieważ to określa kolejność wykonywania. W naszym przypadku zadania w etapie build wykonują się przed zadaniami w etapie test. GitLab runner wykona zadania w tym samym etapie równolegle i poczeka na zakończenie wszystkich zadań przed rozpoczęciem wykonywania zadań w następnym etapie.

• Pamięć podręczna

Definicja cache jest dołączona, aby określić pliki i katalogi, które będą buforowane lub zapisywane do późniejszego użycia między uruchomieniami zadań:

Definiowanie buforowania pomaga zminimalizować czas potrzebny na uruchomienie zadań, które zależą od zasobów, które raczej nie zmienią się między uruchomieniami. Określamy katalog node_modules do buforowania. Jest to katalog, w którym npm instaluje zależności dla projektu.

• Zadania

W konfiguracji mamy dwa zadania:

• install_dependencies

Podczas nazywania zadań możesz wybrać dowolną nazwę. Zaleca się jednak stosowanie nazw opisowych, ponieważ są one używane w interfejsie użytkownika GitLab – może to być pomocne podczas debugowania. Większość konfiguracji w sieci łączy npm install z poleceniami w etapie testowym. Rozdzieliliśmy je tylko po to, aby pokazać, jak zadania wchodzą ze sobą w interakcję, ponieważ jest to dość mały projekt. stage dyrektywa oznacza to zadanie jako build – jest ono uruchamiane w etapie build stage.

Dyrektywa script określa polecenia do uruchomienia podczas wykonywania tego zadania. Możesz określić wiele poleceń, dodając linie wewnątrz bloku script . Oczywiście musisz uważać na prawidłowe wcięcia i pamiętać o kolejności, w jakiej skrypty powinny być wykonywane.

Dyrektywa artifacts określa pliki lub ścieżki katalogów do zapisania i udostępnienia między etapami. Ponownie przypominamy, że właściwe uporządkowanie etapów ma kluczowe znaczenie dla upewnienia się, że inne pliki będą miały to, czego potrzebują do wykonania. Polecenie npm install zainstaluje zależności w katalogu node_modules . Deklarując go w sekcji artifacts, udostępniamy go zadaniom wykonywanym w kolejnych etapach. Pliki te są również dostępne w interfejsie GitLab, jeśli chcesz je pobrać.

• test_with_mocha

To zadanie jest uruchamiane w etapie test. Ponieważ to zadanie jest uruchamiane po zakończeniu zadania w etapie build, artefakty zadeklarowane w etapie build (które są zależnościami dla naszej aplikacji) będą dostępne dla etapu test. Blok script określa polecenia npm do uruchomienia naszych testów. Najpierw uruchamiamy naszą aplikację, a następnie przeprowadzamy testy na aplikacji. Uruchomienie tych poleceń wywołuje polecenia określone w sekcji bloku skryptu package.json:
Dzięki temu powinieneś mieć podstawowe zrozumienie pliku .gitlab-ci.yml. Mówimy podstawowe, ponieważ jest to tylko statyczna aplikacja hello world. Następnie zobaczmy, jak możemy wyzwolić nowe uruchomienie CI.

Krok 3: Wyzwalanie uruchomienia GitLab CI

Z pewnością ucieszy Cię fakt, że gdy tylko Twoje repozytorium będzie zawierać plik .gitlab-ci.yml, wszelkie nowe commity, które do niego wypchniesz, wyzwolą nowe uruchomienie ciągłej integracji (Continuous Integration). W przypadku samodzielnie zarządzanych instancji GitLab, jeśli nie skonfigurowałeś runnera GitLab, uruchomienie CI zostanie ustawione na „pending” (oczekujące).

GitLab SaaS udostępnia użytkownikom współdzielone runnery (shared runners), które mogą automatycznie pobierać ich zadania i je wykonywać. Jest to możliwe tylko wtedy, gdy współdzielone runnery są wolne i nie przekroczyłeś swojego limitu. W GitLab SaaS możesz wybrać, czy chcesz, aby Twoje repozytorium korzystało ze współdzielonych runnerów (shared runners) czy nie, przechodząc do Settings > CI / CD swojego projektu, jak pokazano na poniższym zrzucie ekranu. Na tej stronie znajdziesz również informacje dotyczące instrukcji instalacji runnera GitLab, w które zagłębimy się w następnym kroku:

Teraz wprowadźmy małą zmianę, aby wyzwolić uruchomienie CI. Przejdź z powrotem do swojego repozytorium projektu GitLab node_pipeline:

Kliknij plik README.md wyróżniony powyżej, aby go wyświetlić:

Kliknij przycisk ‘Edit’, aby otworzyć plik do edycji w przeglądarce, i dodaj trochę tekstu:

Po dodaniu tekstu przewiń w dół i kliknij przycisk Commit changes, aby zapisać zmiany. Możesz dowolnie zmodyfikować komunikat zatwierdzenia (commit message). Pojawi się on jako tytuł w interfejsie GitLab, gdy potok (pipeline) będzie uruchomiony. Pozostawiliśmy go jako Update README.md, ponieważ jest to dość opisowe:

Po zatwierdzeniu zmian wróć do głównej strony projektu. Zauważysz małą ikonę wstrzymania (paused) dołączoną do najnowszego commitu. Po najechaniu myszą na ikonę wyświetli się komunikat: ‘Pipeline:pending’:

Oznacza to, że uruchomienie CI zostało wyzwolone. Jednak testy nie zostały jeszcze uruchomione. W menu nawigacyjnym po lewej stronie kliknij CI/CD, a następnie wybierz Pipelines. Spowoduje to otwarcie strony pokazującej więcej szczegółów na temat potoku. Możesz zobaczyć, że CI ma status pending (oczekujący) i jest oznaczone jako zablokowane (stuck):

Aby uzyskać więcej szczegółów na temat uruchomienia, kliknij status pending. Zobaczysz poniższy widok, wyświetlający różne etapy uruchomienia oraz poszczególne zadania powiązane z każdym etapem:

Możesz również kliknąć poszczególne zadania, aby zobaczyć ich szczegóły, takie jak przyczyny opóźnień. W przypadku nieudanych uruchomień, to tutaj zobaczysz, co spowodowało niepowodzenie zadania:

Komunikat wskazuje, że zadanie utknęło, ponieważ nie skonfigurowano żadnych aktywnych runnerów, które mogłyby je wykonać. Zrobimy to w następnym kroku. Gdy udostępnisz runnera, zadanie rozpocznie się automatycznie. Podczas wykonywania zadania zobaczysz dane wyjściowe w tym interfejsie, a także inne artefakty do pobrania wygenerowane podczas działania zadania.

Krok 4: Konfiguracja usługi GitLab CI Runner

Nadszedł czas, aby skorzystać z drugiego serwera, który zadeklarowaliśmy w sekcji Wymagania wstępne tego samouczka. Na tym serwerze zainstalujemy i skonfigurujemy usługę GitLab runner. Możesz wdrożyć tę usługę, aby uruchomić wiele instancji runnerów dla różnych projektów w GitLabie.

Masz możliwość wdrożenia runnera na tym samym serwerze, który hostuje Twoją samodzielnie zarządzaną instancję GitLaba. Jednak aby upewnić się, że instancja nie jest ograniczona zasobami, lepiej jest skonfigurować osobną instancję CI runnera. Niezależnie od wybranej konfiguracji, Docker musi być zainstalowany , aby odizolować środowiska testowe.

Proces instalacji GitLab CI runnera jest porównywalny z procesem instalacji samodzielnie zarządzanej instancji GitLab. Zaczynamy od pobrania skryptu dodającego oficjalne repozytorium GitLab do źródeł apt za pomocą następującego polecenia:

Podaj hasło roota, gdy zostaniesz o to poproszony. Następnie możesz uruchomić polecenie instalujące najnowszą wersję GitLab CI runnera:

Powyższe polecenie instaluje i rejestruje usługę runnera gotową do użycia w Twoich projektach.

Krok 5: Uzyskiwanie tokenów rejestracyjnych i łączenie GitLab Runnera

Aby skonfigurować GitLab CI runnera do przyjmowania zadań, potrzebujesz tokenu runnera GitLab. Jest on wymagany, aby runner mógł uwierzytelnić się na Twoim serwerze GitLab. Istnieją dwa rodzaje tokenów, w zależności od tego, jak chcesz korzystać z runnera: specyficzne dla projektu oraz współdzielone.

Runnery specyficzne dla projektu mają zastosowanie, jeśli masz unikalne wymagania dotyczące runnera. Na przykład, jeśli masz definicje wdrożenia w swoim pliku gitlab-ci.yml z unikalnymi tokenami, zalecany może być specyficzny runner do poprawnego uwierzytelnienia w środowisku wdrażania. Inną kwestią jest to, czy etapy ciągłej integracji zawierają procesy wymagające dużych zasobów. Wtedy idealnym rozwiązaniem byłoby użycie runnera specyficznego dla projektu. Pamiętaj, że runner specyficzny dla projektu nie przyjmuje zadań z innych projektów.

Współdzielone runnery są ogólnego przeznaczenia i mogą być używane przez wiele projektów. Instancja GitLab SaaS hostowana na GitLab Inc posiada współdzielone runnery, które automatycznie przejmą Twoje potoki, jak wyjaśniono w Kroku trzecim. Runnery pobierają zadania z Twoich konfiguracji na podstawie algorytmu uwzględniającego liczbę zadań aktualnie wykonywanych dla każdego projektu. Współdzielony runner jest bardziej elastyczny niż runner specyficzny. Można go skonfigurować z konta administratora instancji GitLab. Zobaczmy, jak możemy uzyskać tokeny dla obu runnerów.

• Rejestracja runnera specyficznego dla projektu

Aby zarejestrować runnera specyficznego dla projektu, otwórz swój projekt w instancji GitLab lub na koncie GitLab SaaS. Z menu nawigacyjnego po lewej stronie kliknij pozycję Settings i wybierz opcję CI/CD:

Następnie przewiń w dół do sekcji Runners i kliknij przycisk, aby rozwinąć sekcję:

Lewa strona wyjaśnia, jak zarejestrować runnera specyficznego dla projektu. Jest to widok instancji GitLab SaaS. Możesz również skonfigurować automatyczne runnery za pomocą Kubernetes, ale w tym samouczku zajmujemy się runnerem ręcznym:

Następnie musisz skupić się na sekcji, w której podany jest token dla tego projektu. W przypadku samodzielnie zarządzanej instancji GitLab, adres URL wyświetli domenę serwera, na którym działa Twoja instancja GitLab:

Możesz wyłączyć współdzielone runnery dla tego projektu, przełączając przełącznik w sekcji po prawej stronie pod Shared Runners. Następnie skopiuj wyświetlony token rejestracyjny do notatnika, ponieważ użyjemy go później.

• Rejestrowanie współdzielonego runnera

Aby zarejestrować współdzielonego runnera, musisz zalogować się do swojej samodzielnie zarządzanej instancji GitLab jako administrator. Aby uzyskać dostęp do panelu administracyjnego, kliknij ikonę klucza w górnym menu nawigacyjnym:

W Panelu administracyjnym, kliknij Runners w sekcji Overview lewego menu. Spowoduje to otwarcie strony z instrukcjami konfiguracji Shared Runners:

Skopiuj token rejestracyjny wyświetlony po prawej stronie pod Set up a shared Runner manually. Użyjesz tego tokenu do zarejestrowania runnera w następnym kroku.

• Łączenie runnera GitLab CI z instancją GitLab

W tym kroku połączysz swoją instancję GitLab z runnerem CI. Zaloguj się ponownie na serwer, na którym zainstalowałeś usługę GitLab runner w Kroku czwartym. Aby rozpocząć proces rejestracji runnera, wprowadź następujące polecenie w terminalu:

Polecenie zada Ci serię pytań:

• Wprowadź adres URL instancji GitLab (na przykład https://gitlab.com/):

Podaj nazwę domeny swojej instancji GitLab, używając https:// w celu określenia SSL.

• Wprowadź token rejestracyjny:

Podaj swój token rejestracyjny. W tym miejscu wybierzesz, czy chcesz, aby ten runner był przypisany do konkretnego projektu, czy współdzielony. Możesz podać tylko jeden z wcześniej skopiowanych tokenów dla jednej z tych opcji.

• Wprowadź opis dla runnera:

Wybierz opisową nazwę dla swojego runnera CI, ponieważ będzie ona widoczna w interfejsie użytkownika instancji GitLab.

• Wybierz executor (wykonawcę): custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Tutaj dostępne są opcje wyboru executora do uruchamiania zadań. Wpisz Docker.

• Wprowadź tagi dla runnera (rozdzielone przecinkami):

To jest opcjonalne. Możesz wprowadzić dowolne nazwy tagów, takie jak zależności, które zawiera ten runner. Na razie możesz pozostawić to pole puste.

• Wprowadź domyślny obraz Dockera (na przykład ruby:2.6):

W tym miejscu należy określić domyślny obraz ogólnego przeznaczenia używany do uruchamiania zadań, na wypadek gdyby plik gitlab-ci.yml nie określał obrazu. Wpisz alpine:latest, ponieważ jest to mały, bezpieczny obraz ogólnego przeznaczenia. Naciśnij Enter, a runner zostanie automatycznie zarejestrowany i uruchomiony:

Aby wyświetlić listę aktualnie dostępnych runnerów, wprowadź następujące polecenie:

Krok 6: Potwierdzenie pomyślnego połączenia runnera CI w GitLabie

Następnie wróć do przeglądarki i odwiedź stronę swojego projektu w instancji GitLab. W zależności od tego, ile minut minęło od zarejestrowania runnera, możesz zobaczyć, że zadanie jest obecnie uruchomione:

Lub mogło zostać już zakończone:

Następnie przejdź do strony Pipelines albo za pomocą lewego menu CI/CD > Pipelines, lub klikając na ikonę running, passed, lub failed (jeśli potok napotkał błędy), aby wyświetlić stan uruchomienia CI. Tutaj widzimy, że jeden z etapów (build stage) zakończył się pomyślnie, podczas gdy jeden wciąż trwa:

W tabeli, pod nagłówkiem Stages, kliknij jedną z ikon etapów, aby wyświetlić powiązane zadania:

Następnie kliknij zadanie w wyskakującym oknie, aby wyświetlić szczegóły:

Zadanie zostało uruchomione i możesz zobaczyć postęp, gdy polecenie npm instalowało zależności. Po prawej stronie możesz zobaczyć inne powiązane informacje. Masz możliwość pobrania artefaktów z zadania. Możesz także przełączać się między etapami z rozwijanego menu, aby zobaczyć inne zadania.

Tutaj możesz zobaczyć nasze przypadki testowe pokazujące się po wybraniu zadania na etapie testowym:

Dostępne runnery

W lewym menu, jeśli klikniesz Settings > CI/CD, i rozwiniesz sekcję Runners sekcji powinieneś zobaczyć runnera, którego właśnie zarejestrowałeś. W zależności od tego, czy określiłeś token specyficzny dla projektu, czy token współdzielony, runner pojawi się odpowiednio w danej sekcji.

Tutaj widać, że zarejestrowaliśmy token specyficzny dla projektu. Runner pojawia się w sekcji Specyficzne runnery:

Podsumowanie

W tym samouczku dowiedziałeś się, jak zautomatyzować testy za pomocą GitLab CI. Rozpoczęliśmy od skonfigurowania projektu aplikacji Node.js na GitLabie. Projekt zawierał kilka przypadków testowych oraz gitlab-ci.yml. Dowiedzieliśmy się, że GitLab używa gitlab-ci.yml do określenia, co zrobić po wyzwoleniu. Plik gitlab-ci.yml jest po prostu plikiem konfiguracyjnym zawierającym instrukcje dotyczące budowania i testowania aplikacji, zapisanym w formacie YAML, który runner GitLab CI potrafi zrozumieć.

Udało nam się również skonfigurować runnera GitLab CI na osobnym hoście. Zarejestrowaliśmy go, aby pobierał zadania z naszych instancji GitLaba za każdym razem, gdy pojawia się wyzwalacz. Choć był to prosty projekt, możesz wykorzystać te informacje do skonfigurowania potoków dla złożonych projektów. Kroki dodawania projektu do GitLaba i łączenia runnera GitLab CI pozostają takie same. Zmieniają się jedynie instrukcje i etapy w pliku gitlab-ci.yml.

Miłego korzystania!