Jak skonfigurować potoki ciągłej integracji GitHub z runnerami self-hosted na Ubuntu 22.04.

Wprowadzenie

Inżynieria oprogramowania to szybka i konkurencyjna dziedzina. Szybsze wdrażanie produktów dla użytkowników da Ci przewagę nad konkurencją. Z drugiej strony, istnieją najlepsze praktyki branżowe, które pomagają firmom wyrównać szanse.

Ciągła integracja i ciągłe wdrażanie (CICD) to przykład strategii, która wykorzystuje najlepsze praktyki branżowe, aby dać firmom przewagę w tej konkurencyjnej dziedzinie.

GitHub, internetowe repozytorium z systemem Git, narzędziem do kontroli wersji, pozwala programistom, inżynierom i architektom oprogramowania na wdrażanie CI/CD. Ciągły Rozwój (CD) to praktyka automatyzacji kompilacji, testów i wdrożeń. Ciągła Integracja (CI) umożliwia wielu osobom współpracę nad tym samym projektem i sprawdzanie, czy kod działa, bez obaw o konflikty scalania.

GitHub Actions pozwalają nam pisać kroki, które automatyzują kompilacje, testy i wdrożenia.

W tym samouczku dowiesz się, jak skonfigurować Ciągłą Integrację za pomocą GitHub Actions. Zaczniemy od skonfigurowania repozytorium Git do przechowywania naszego kodu. Następnie skonfigurujemy proces GitHub CI do monitorowania zmian w naszym kodzie, uruchomienia runnera CI w celu przeprowadzenia testów, zbudowania i wdrożenia naszej aplikacji na serwerze Ubuntu 22.04 z uruchomionym Nginx.

Wymagania wstępne

Aby móc śledzić ten samouczek, będziesz potrzebować:

• Serwera z systemem Ubuntu 22.04. Możesz postępować zgodnie z tym samouczkiem w celu początkowej konfiguracji serwera Ubuntu, dodania użytkownika innego niż root, oraz włączenia zapory sieciowej UFW systemu Ubuntu.

• Będziesz potrzebować zainstalowanego Node.js na swoim serwerze, najlepiej w wersji 14 lub nowszej. Mamy samouczek na temat jak zainstalować Node.js na Ubuntu.

• Będziesz potrzebować zainstalowanego oprogramowania serwera Nginx. Mamy przewodnik na temat Jak zainstalować Nginx na serwerze z systemem Ubuntu.

• Będziesz potrzebować Docker i Docker Compose zainstalowanych na lokalnym komputerze, aby uruchomić odizolowane środowisko programistyczne. Postępuj zgodnie z naszym samouczkiem, aby dowiedzieć się Jak zainstalować i obsługiwać Docker w chmurze.

Skoro mamy już wszystko, czego potrzebujemy, zacznijmy.

Krok 1. Klonowanie repozytorium projektu.

Oprzemy ten samouczek na Reactjs, deklaratywnej bibliotece JavaScript do budowania interfejsów użytkownika. Jeśli chcesz skonfigurować nowy projekt od zera, możesz skorzystać z tego zasobu dotyczącego konfiguracji aplikacji React. Dla zwięzłości użyjemy klonu tego repozytorium React.js które już skonfigurowaliśmy na GitHubie.

Aplikacja, którą klonujemy, to prosta aplikacja React z react-router 6 i testem wykonanym za pomocą React Testing Library, co daje nam metody dostępu do DOM.

Aby sklonować repozytorium, kliknij zielony przycisk i skopiuj adres URL.

Otwórz terminal w swoim obszarze roboczym i uruchom poniższe polecenie, aby sklonować aplikację:

Po sklonowaniu repozytorium przejdź do katalogu projektu:

Uruchom polecenie docker-compose up, aby zbudować i uruchomić aplikację:

Po zakończeniu procesu odwiedź http://localhost:3000

Powinieneś zobaczyć coś podobnego do tego:

Krok 2. Zrozumienie pliku Node.js.yml.

W tym kroku zdefiniujemy dyrektywy w pliku YAML GitHub, aby pomóc nam zrozumieć, co się dzieje. W repozytorium znajduje się katalog .github/workflows zawierający plik node.js.yml, który zawiera kroki przepływu pracy (workflow), które wykonują runnery GitHub po przesłaniu zmian do repozytorium kodu na GitHubie. YAML składnia jest używana do pisania przepływów pracy dla GitHub Actions. Pliki YAML kończą się rozszerzeniem yaml lub yml.

Otwórz plik node.js.yml, powinien on wyglądać następująco:

W momencie pisania tego samouczka używaliśmy wersji 16 Node.js 16. Teraz zrozummy przepływ pracy (workflow) GitHub Actions:

• name

name: cicd-tut

Nazwa Twojego przepływu pracy, ta nazwa będzie wyświetlana w zakładce Actions repozytorium.

• on

on służy do definiowania zdarzeń. Zdarzenia mogą automatycznie wyzwalać przepływ pracy lub być zaplanowane na później. Zdarzenia mogą być pojedyncze lub wielokrotne, można również określić wykonywanie przepływu pracy dla określonych gałęzi, tagów lub plików. Działa to jak filtr.

W naszym pliku YAML definiujemy wiele automatycznych zdarzeń, są to:

• Zdarzenie push jest wyzwalane, gdy kod jest zatwierdzany (commit) do repozytorium

• Zdarzenie pull_request jest wyzwalane, gdy tworzone jest żądanie ściągnięcia (pull request) w gałęzi głównej.

Określamy nazwę gałęzi main w celu ograniczenia wykonywania przepływu pracy tylko do tej gałęzi. Możemy również określić gałęzie, które mają być ignorowane, używając wykrzyknika ! przed nazwą gałęzi.

• jobs

Przepływ pracy składa się zasadniczo z jednego lub kilku zadań. Zadania te są uruchamiane kolejno, od pierwszego do ostatniego.

Każde zadanie działa w środowisku uruchomieniowym (runner) określonym przez runs-on. Możesz wybrać uruchamianie zadań na runnerach GitHub oznaczonych jako ubuntu-latest lub na self-hosted runnerze oznaczonym jako self-hosted. Twój wybór będzie zależał od liczby potrzebnych zadań. Dzięki własnym runnerom (self-hosted) masz większą elastyczność i kontrolę nad zasobami.

W następnym kroku najpierw uruchomimy nasze zadania na runnerach GitHub, a później skonfigurujemy własny runner GitHub (self-hosted) na naszym własnym serwerze.

• strategy

Strategia pozwala nam używać zmiennych w definicji pojedynczego zadania, aby automatycznie tworzyć wiele uruchomień zadań w oparciu o kombinacje zmiennych.

W naszym pliku YAML mamy jedną zmienną dla wersji node, ale jeśli dodamy kolejną dla wersji node 18, w ten sposób: node-version: [16.x, 18.x], wtedy strategia macierzy (matrix) utworzy 2 uruchomienia zadań dla naszej aplikacji React, zarówno dla wersji Node 16, jak i 18.

• steps

Kroki (steps) to sekwencja zadań składających się na zadanie. Kroki mogą uruchamiać polecenia, konfigurować zadania, uruchamiać akcje w Twoim publicznym repozytorium lub akcje opublikowane w rejestrze Docker.

Krok ma nazwę. Chociaż jest ona opcjonalna, możesz jej użyć, aby w łatwy sposób określić nazwę kroku, która będzie wyświetlana w serwisie GitHub.

W kroku możesz wybrać akcję do uruchomienia w swoim zadaniu; akcje są wielokrotnego użytku. Wersje akcji są określane podczas definiowania akcji, co jest ważne, ponieważ zapobiega przerwaniu działania przepływu pracy, gdy właściciel akcji opublikuje aktualizację.

W powyższym fragmencie kodu, checkout@v3 jest przykładem akcji z określoną wersją 3. Ta akcja pobiera Twoje repozytorium, dzięki czemu Twój przepływ pracy ma do niego dostęp.

Niektóre akcje, takie jak actions/setup-node@v3 powyżej, mają dane wejściowe oznaczone za pomocą with słowa kluczowego, akcje setup node wymagają wersji Node 16 oraz buforowania npm.

• run

Ta akcja uruchamia programy wiersza poleceń przy użyciu powłoki systemu operacyjnego.

W powyższym pliku YAML mamy trzy polecenia, wszystkie zostaną uruchomione przy użyciu tej samej powłoki w środowisku runnera.

• Pierwsze polecenie npm i instaluje wszystkie zależności wymagane przez naszą aplikację React.

• Drugie npm test, uruchamia napisany przez nas test. Test oczekuje, że tekst learn react zostanie wyrenderowany na stronie głównej.

• Na koniec, npm run build tworzy katalog produkcyjny (build) z wersją produkcyjną naszej aplikacji. Później użyjemy tego katalogu w naszym bloku serwera Nginx.

Krok 3. Testowanie GitHub CI za pomocą GitHub Runners.

W tym kroku przetestujemy proces ciągłej integracji (Continuous Integration) za pomocą runnerów GitHub. Zacznij od otwarcia pliku node.js.yml. Zmień typ runnera, na którym będą uruchamiane akcje, na ubuntu-latest. Celem tego jest przetestowanie, czy przepływ pracy GitHub działa idealnie na runnerach GitHub przed skonfigurowaniem naszych własnych, hostowanych samodzielnie runnerów (self-hosted).

Utwórz nowe repozytorium na swoim koncie GitHub. Zanim przejdziemy dalej, wróć do katalogu roboczego i usuń katalog .git, jeśli go nie widzisz, sprawdź ukryte pliki. Możesz użyć następującego polecenia w terminalu, aby usunąć ten katalog:

Teraz możesz dodać wszystkie pliki projektu za pomocą git add, zatwierdzić (commit) i przesłać (push) je do swojego repozytorium. W razie problemów skorzystaj z tego przewodnika dotyczącego łączenia folderu projektu z repozytorium GitHub utworzonym powyżej.

Po zakończeniu kliknij kartę Code w swoim repozytorium. Obok całkowitej liczby zatwierdzeń zobaczysz małą pomarańczową kropkę. Po jej kliknięciu pojawi się okno modalne podobne do poniższego, wskazujące, że Twój przepływ pracy został dodany do kolejki:

Now kliknij link Details w oknie modalnym lub przejdź do karty Actions, gdzie zobaczysz każdy krok przepływu pracy node.js.yml uruchamiany przez runnery GitHub:

Jeśli operacja zakończy się powodzeniem, kliknij kartę Actions, powinna ona wyglądać następująco:

I to wszystko, mała pomarańczowa kropka na naszej karcie Code powinna teraz zmienić się w zielony znacznik wyboru. Runner GitHub pomyślnie zbudował naszą aplikację.

Now, pójdźmy o krok dalej i zmieńmy środowisko budowania, aby korzystać z własnych runnerów GitHub (self-hosted) w naszej własnej infrastrukturze serwerowej Ubuntu.

Krok 4. Konfigurowanie przepływu pracy GitHub do korzystania z własnego runnera (self-hosted).

Zanim zainstalujemy własnego runnera na naszym serwerze, wróćmy do naszego obszaru roboczego i edytujmy plik przepływu pracy node.js.yml  aby uruchamiał się na własnych runnerach GitHub (self-hosted).

Na tym etapie, po zatwierdzeniu zmian, zadanie zostanie dodane do kolejki, ponieważ własny runner (self-hosted) nie został jeszcze zdefiniowany.

W swoim repozytorium kliknij kartę Settings, na lewym pasku bocznym kliknij Actions, a następnie kliknij Runners:

Kliknij New self-hosted runner, a następnie wybierz Linux jako system operacyjny.

Zobaczysz instrukcje pokazujące, jak pobrać runnera i zainstalować go na swoim serwerze.

Krok 5. Instalacja i konfiguracja własnego runnera GitHub (self-hosted) na naszym serwerze.

W tym kroku skonfigurujemy własnego runnera GitHub (self-hosted runner). Własny runner to system, który może wdrażać i zarządzać wykonywaniem zadań z GitHub Actions na stronie GitHub. Jedną z zalet własnego runnera nad runnerem hostowanym przez GitHub jest elastyczność. Oferuje on większą kontrolę nad systemem operacyjnym, sprzętem i innymi narzędziami, które można dostosować do potrzeb danej aplikacji.

Własne runnery można dodawać na różnych poziomach, takich jak:

• Runnery na poziomie repozytorium – są one dedykowane dla jednego repozytorium.

• Runnery na poziomie organizacji – mogą przetwarzać zadania dla wielu repozytoriów w organizacji.

• Na poziomie przedsiębiorstwa (enterprise) – mogą być przypisane do wielu organizacji.

Aby kontynuować, zaloguj się na swój serwer przez SSH:

Przejdź do swojego katalogu domowego za pomocą polecenia:

Następnie utwórz katalog o nazwie action-runners i przejdź do niego:

Następnie pobierz najnowszą wersję pakietu runnera:

Następnie rozpakuj pobrany pakiet za pomocą polecenia:

Wróć do swojego repozytorium, w zakładce Settings, w panelu po lewej stronie kliknij Actions, a następnie Runners, dokładnie tak, jak zrobiliśmy to w Kroku 4.

Zobaczysz listę poleceń zawierającą token łączący Twój własny runner z repozytorium GitHub. Będąc wciąż w katalogu, do którego rozpakowano kod runnera GitHub, użyj podanego polecenia, aby połączyć swój runner, na przykład:

Uwierzytelnianie powinno zakończyć się sukcesem:

Naciśnij Enter dla domyślnej grupy runnerów (Default).

Następnie wprowadź nazwę dla swojego runnera, na przykład my-runner, i naciśnij Enter.

Naciśnij Enter, aby pominąć dodawanie dodatkowych etykiet. Powinieneś zobaczyć komunikat o sukcesie, jak na poniższym zrzucie ekranu:

Wprowadź nazwę swojego katalogu roboczego, na przykład react-cicd, co powinno zakończyć się sukcesem i wyświetleniem tekstu settings saved.

Na koniec uruchom ./run.sh, co powinno wyświetlić Connected to Github:

Jednak to polecenie nie działa w tle. Jeśli wpiszemy ctrl+c w naszym terminalu, runner zostanie zatrzymany. Musimy zastąpić go usługą .svc.sh , aby utrzymać działanie runnera jako usługi, dzięki czemu będziemy mogli nadal z nim wchodzić w interakcję.

Zatrzymaj runnera za pomocą ctrl+c. Możesz zainstalować usługę .svc.sh uruchamiając polecenie:

Po zainstalowaniu uruchom usługę za pomocą polecenia:

Powinno to zakończyć się sukcesem, pokazując active (running).

Aby potwierdzić, że usługa svc.sh działa, wykonaj polecenie:

W tym momencie każdy przepływ pracy (workflow), który mógł oczekiwać w kolejce na własny runner, powinien uruchomić się pomyślnie. Możesz również edytować plik i przetestować działanie. Na przykład zmodyfikuj plik O nas.tsx, zatwierdź (commit) i wypchnij (push) zmiany, a własny runner pomyślnie ukończy zadanie.

Krok 6. Konfiguracja bloku serwera Nginx

W tym kroku skonfigurujemy blok serwera w Nginx, aby wyświetlić wersję produkcyjną (build) naszej aplikacji React. Mamy poradnik na temat Konfiguracji bloków serwera Nginx, który może okazać się pomocny.

Poniżej znajduje się przykład bloku serwera użytego w tym poradniku:

Utworzysz plik konfiguracyjny bloku serwera Nginx wewnątrz katalogu /etc/nginx/sites-available .

Otwórz plik konfiguracyjny bloku serwera swojej witryny w edytorze nano za pomocą polecenia:

Skopiuj udostępniony powyżej blok serwera, dostosuj go do swoich ścieżek katalogów i wklej do otwieranego pliku. Po zakończeniu edycji naciśnij ctrl+x , a następnie naciśnij y oraz enter , aby zapisać i wyjść.

Po zapisaniu utwórz dowiązanie symboliczne dla konfiguracji bloku serwera react-cicd z /etc/nginx/sites-available do /etc/nginx/sites-enabled , uruchamiając polecenie:

Aby zmiany weszły w życie, musisz zrestartować Nginx. Jednak zanim zrestartujesz usługę Nginx, przetestuj, czy konfiguracje Nginx są poprawne, uruchamiając polecenie:

Jeśli konfiguracja jest poprawna, test powinien zakończyć się pomyślnie.

Zwróć uwagę na wartość server_name dyrektywy “ react.test ” w bloku serwera? Dodasz tę wartość w swoim pliku hosts na swoim lokalnym komputerze. Umożliwi to otwarcie aplikacji w przeglądarce. Ten krok jest konieczny tylko w przypadku domen wirtualnych używanych w lokalnych środowiskach programistycznych. Jeśli masz zarejestrowaną nazwę domeny powiązaną z publicznym adresem IP swojego serwera, nazwa domeny powinna być już dostępna w przeglądarce.

Na swoim lokalnym komputerze otwórz plik hosts za pomocą polecenia:

Wewnątrz pliku hosts dodaj adres IP swojego serwera, np. 127.0.0.1, a następnie nazwę swojej wirtualnej domeny.

Poniżej przedstawiono przykład. Następnie zamknij plik i zapisz:

Wracając do serwera, wewnątrz katalogu /var/www utwórz nowy katalog (możesz nazwać go react-cicd), uruchamiając:

Na tym etapie odkomentujemy ostatnie polecenie w pliku node.js.yml .

To polecenie kopiuje folder kompilacji (build) naszej aplikacji React z miejsca, które określiliśmy jako nasz folder roboczy wewnątrz katalogu actions-runner w poprzednim step 5.

I umieszcza folder public w katalogu /var/www/react-cicd .

Blok serwera może teraz uzyskać dostęp do naszej aplikacji i wyświetlić ją w przeglądarce.

Na koniec zrestartuj usługę Nginx za pomocą polecenia:

Teraz możesz wprowadzić zmianę w pliku O nas.tsx , a następnie zatwierdzić (commit) i przesłać (push) zmiany do swojego repozytorium. Po pomyślnej kompilacji zobaczysz skompilowaną wersję swojej aplikacji React pod adresem http://react.test lub pod określoną nazwą domeny. Unikaj edycji elementu href w pliku Home.tsx , ponieważ może to spowodować niepowodzenie już napisanego testu. Karta Actions w Twoim repozytorium powinna również pokazywać ukończone zadanie kompilacji.

Podsumowanie

Ciągła integracja z Github Actions niesie ze sobą wiele korzyści, w tym świetne doświadczenia programistów, pomaga w ciągłym testowaniu, ułatwia współpracę w większych zespołach, skraca czas programowania, pozwala na szybkie wydawanie nowych funkcji, zapewnia informacje zwrotne w czasie rzeczywistym i satysfakcję klientów, dając Ci przewagę nad konkurencją. Aby poszerzyć tę wiedzę, możesz również dowiedzieć się o konfigurowaniu potoków ciągłej integracji (CI) GitLab na systemie Ubuntu. oraz o używaniu samodzielnie zarządzanej instancji GitLab do hostowania obrazów Docker i uruchamiania prywatnych kompilacji.

Udanego kodowania!