Platformy Technologiczne Laboratorium nr 6 Java: Ciągła integracja (ang. Continuous Integration) Praca z repozytorium git w salach laboratoryjnych. W niektórych salach laboratoryjnych występują problemy w czasie obsługi repozytorium za pośrednictwem środowiska Netbeans (komunikaty Cannot connect to repository). Wszystkie operacje na repozytorium można zrealizować za pomocą polecenia git w konsoli tekstowej w instrukcji podano zarówno lokalizację potrzebnych opcji w menu Netbeansa, jak i odpowiadające im polecenia do użycia w terminalu. Hasła do repozytorium w systemach Windows. Konsolowy klient git w systemach Windows wykorzystuje domyślnie systemową usługę Menadżer poświadczeń w celu zapisania loginu i hasła do repozytorium. Dzięki temu nie trzeba wpisywać hasła przy każdej operacji typu push/pull. Po zakończeniu pracy w sali laboratoryjnej należy usunąć swoje hasło zapisane w Menadżerze poświadczeń (opis poniżej). Przez rozpoczęciem pracy należy sprawdzić, czy w Menadżerze nie znajduje się hasło pozostawione przez studenta z poprzedniej grupy jego obecność uniemożliwi pracę ze zdalnym repozytorium. Hasła zapisane za pomocą Menadżera poświadczeń można sprawdzić w Panelu sterowania, kategoria Konta użytkowników, pozycja Poświadczenia systemu Windows. Należy usunąć pozycję, w której występuje domena gitlab.comcute.eti.pg.gda.pl: W celu realizacji zadania należy dobrać się w dwuosobowe zespoły. Jeśli liczba osób w grupie laboratoryjnej jest nieparzysta, dopuszczalny jest zespół 3 osobowy. Zadanie polega na rozbudowie aplikacji przygotowanej przez jednego z członków zespołu na poprzednich zajęciach laboratoryjnych. Należy w tym celu wykorzystać narzędzia wspomagające pracę w grupie. W. Korłub 1
Prowadzący podaje na początku zajęć nowe funkcjonalności do zaimplementowania w aplikacji (minimum jedna funkcjonalność dla każdego członka zespołu), np.: możliwość wyszukiwania produktów o cenie mniejszej/większej niż wartość podanego parametru, możliwość wyszukiwania zamówień, które zawierają wskazany produkt, możliwość wyszukiwania produktów po fragmencie nazwy (np. książek po fragmencie tytułu), możliwość wyszukiwania produktów, dla których liczba dostępnych sztuk jest mniejsza niż podany parametr, wyszukiwania oparte o specyficzne cechy produktów, np.: o wyszukiwanie książek, które posiadają nie więcej niż x stron, o wyszukiwanie filmów, które trwają nie dłużej niż x minut, o wyszukiwanie płyt CD, które zawierają przynajmniej x piosenek. Aby rozpocząć realizację zadania, należy założyć konto w serwisie GitLab pod adresem: https://gitlab.comcute.eti.pg.gda.pl/. Rejestracja jest możliwa przy użyciu politechnicznego adresu e-mail. Serwis gitlab.comcute.eti.pg.gda.pl został udostępniony na potrzeby zajęć laboratoryjnych nie należy przechowywać w nim projektów niezwiązanych z przedmiotem Platformy technologiczne. Repozytoria zostaną wyczyszczone po zakończeniu realizacji zadań. GitLab jest zintegrowanym środowiskiem do organizacji pracy zespołu. Obejmuje ono: repozytorium kontroli wersji (git), moduł zarządzania zadaniami (ang. bug tracker), moduł ciągłej integracji (ang. continuous integration budowanie i testowanie aplikacji na serwerze), narzędzia do inspekcji kodu (ang. code review), dokumentację projektu (wiki), moduł statystyk oraz inne przydatne narzędzia. Po rejestracji w serwisie GitLab jeden z członków zespołu zakłada nowy projekt przycisk New Project: Należy określić nazwę projektu, jego poziom widoczności ustawić na prywatny, a następnie zatwierdzić formularz. Po zainicjowaniu projektu wyświetlone zostaną informacje, w jaki sposób można dokonać importu kodu źródłowego istniejącej już aplikacji do repozytorium kontroli wersji. Student, który założył projekt, importuje do repozytorium swoją aplikację z laboratorium nr 5. Można to zrobić wywołując polecenie git w konsoli tekstowej lub wykorzystując narzędzia zintegrowane w IDE. W pierwszym przypadku należy postępować zgodnie z instrukcjami wyświetlonymi w serwisie GitLab: Import istniejącego projektu do repozytorium git cd katalog_projektu git init git remote add origin https://login@gitlab.comcute.eti.pg.gda.pl/login/nazwa_projektu.git W. Korłub 2
git add. git commit m"initial import" git push -u origin master Aby zaimportować projekt do repozytorium z poziomu środowiska Netbeans należy wykonać następujące kroki: 1. W celu zainicjowania repozytorium git w katalogu projektu należy wybrać z menu pozycję: Team > Git > Initialize Repository, a następnie zatwierdzić ścieżkę do projektu na dysku w oknie dialogowym. 2. Aby pliki projektu zostały objęte kontrolą wersji, należy kliknąć prawym przyciskiem myszy (ppm) na projekcie w widoku Projects i wybrać z menu kontekstowego pozycję: Git > Add. 3. Wybranie z menu kontekstowego pozycji Git > Commit (ppm na projekcie) spowoduje zapisanie w lokalnym repozytorium pierwszej rewizji obejmującej aktualny stan projektu. Każdy commit do repozytorium powinien być opisany adekwatnym komunikatem (pole Commit Message). W przypadku pierwszej rewizji typowo stosuje się opis: initial import. 4. Aby umieścić zawartość repozytorium na zdalnym serwerze należy wybrać z menu: Team > Remote > Push. W oknie dialogowym należy: a. zaznaczyć opcję Specify Git Repository Location, b. w polu Repository URL podać adres repozytorium odczytany z serwisu GitLab: https://gitlab.comcute.eti.pg.gda.pl/login/nazwa_projektu.git c. pola User oraz Password wypełnić danymi do logowania w serwisie GitLab, a następnie kliknąć przycisk Next, d. w kolejnym kroku wybrać gałąź master (lokalną) i zatwierdzić przyciskiem Next, e. w ostatnim kroku również wybrać gałąź master (na zdalnym serwerze) i zatwierdzić przyciskiem Finish, f. w nowym oknie dialogowym wybrać odpowiedź Yes: Po wykonaniu powyższych operacji należy w przeglądarce internetowej odświeżyć stronę serwisu GitLab i upewnić się, że wszystkie pliki projektu znajdują się w repozytorium. Następnie student, który założył projekt, zaprasza do niego pozostałych członków zespołu. Należy w tym celu przejść na podstronę Settings (1) > Members (2) rysunek poniżej. Następnie należy podać login zapraszanego użytkownika (3) i ustawić jego rolę na Master (4). Na koniec należy zatwierdzić formularz przyciskiem Add to project (5). Od tego momentu pozostali członkowie zespołu będą widzieli projekt na liście swoich projektów i będą mogli go modyfikować. W. Korłub 3
Następnie student, który został zaproszony do projektu, konfiguruje mechanizm ciągłej integracji. Należy w tym celu wybrać przycisk Set up CI znajdujący się na stronie projektu w serwisie GitLab. Następnie należy wprowadzić zawartość pliku konfiguracyjnego.gitlab-ci.yml (poniżej) i zatwierdzić ją przyciskiem Commit Changes. Konfiguracja mechanizmu ciągłej integracji w pliku.gitlab-ci.yml image: maven:3.3.9-jdk-8 stages: - validate - test - package - deploy variables: MAVEN_OPTS: "-Dmaven.repo.local=/opt/maven" MAVEN_CLI_OPTS: "--batch-mode --errors --fail-at-end --show-version" validate-project: stage: validate - 'mvn $MAVEN_CLI_OPTS compile' artifacts: paths: - target expire_in: 30 minutes run-unit-tests: stage: test - 'mvn $MAVEN_CLI_OPTS -Dmaven.main.skip=true test' build-dist: stage: package - 'mvn $MAVEN_CLI_OPTS -Dmaven.main.skip=true -Dmaven.test.skip=true package' W. Korłub 4
artifacts: paths: - target/*.jar deploy-to-test-server: stage: deploy - 'true' deploy-to-production: stage: deploy - 'true' only: - master Powyższa konfiguracja definiuje potok ciągłej integracji (ang. CI pipeline) składający się z czterech etapów. Każdy kolejny etap jest uruchamiany tylko pod warunkiem, że poprzedni zakończył się powodzeniem. Etapy zdefiniowane są w sekcji stages: validate walidacja projektu, weryfikacja poprawności składniowej, kompilacja plików źródłowych; jeśli projekt nie kompiluje się poprawnie, potok zostanie przerwany na tym etapie; test uruchomienie testów jednostkowych, jeśli któryś z testów zakończy się niepowodzeniem, potok zostanie przerwany na tym etapie; package przygotowanie wersji dystrybucyjnej aplikacji (archiwum JAR); deploy wdrożenie aplikacji na serwer testowy i/lub produkcyjny; w środowisku laboratoryjnym nie dysponujemy publicznie dostępnym serwerem produkcyjnym dla każdego zespołu realizującego zadanie, więc w konfiguracji powyżej umieszczono jedynie zaślepki dla tego etapu potoku CI. Wersja dystrybucyjna aplikacji zostanie zbudowana tylko pod warunkiem, że wszystkie testy jednostkowe zakończą się powodzeniem. Wdrożenia aplikacji są wykonywane jedynie w sytuacji, gdy wszystkie wcześniejsze etapy potoku zakończą się sukcesem. Zadania do wykonania w ramach każdego etapu potoku CI są definiowane w dalszej części pliku.gitlab-ci.yml. Przykładowa konfiguracja powyżej obejmuje pięć takich zadań: validate-project, run-unit-tests, build-dist, deploy-to-test-server, deploy-to-production. Każde zadanie posiada atrybut stage określający na jakim etapie potoku ma zostać ono wykonane. Ponadto zadania posiadają atrybuty script, które definiują polecenia do wywołania na serwerze CI. W przypadku projektu budowanego przy użyciu Mavena wykorzystywane jest konsolowe polecenie mvn. Atrybut artifacts pozwala określić jakie efekty danego zadania mają zostać utrwalone. Przykładowo, po wykonaniu zadania build-dist utrwalane jest archiwum JAR z aplikacją. Artefakty są dostępne w czasie wykonywania dalszych zadań w ramach potoku CI oraz mogą zostać pobrane z serwisu GitLab. Z kolei atrybut only umożliwia określenie dla jakich gałęzi repozytorium dane zadanie ma być realizowane. W powyższym przykładzie zadanie deploy-to-production jest uruchamiane tylko dla wersji projektu znajdujących się w gałęzi master repozytorium. Sekcja variables definiuje zmienne do wykorzystania w dalszej części pliku konfiguracyjnego. Zmienna MAVEN_OPTS określa położenie lokalnego repozytorium Mavena, które służy jako cache dla zewnętrznych bibliotek i zależności pobieranych z Internetu. Zmienna MAVEN_CLI_OPTS W. Korłub 5
zawiera opcje wykorzystywane przy wywołaniach polecenia mvn w czasie realizacji zadań zdefiniowanych w ramach potoku CI. Jednym z etapów potoku jest uruchomienie testów jednostkowych. Jeśli wykorzystano przykładowy projekt, który w pliku pom.xml w sekcji <properties> zawiera flagę <surefire.tests.skip>true</surefire.tests.skip>, należy zmienić wartość tej flagi na false. Powyższe ustawienie w połączeniu z konfiguracją plug-ina maven-surefire-plugin (w dalszej części pliku pom.xml) umożliwia określenie czy testy mają być automatycznie uruchamiane przy każdym budowaniu projektu przez Mavena. Jeśli w projekcie znajduje się klasa ContextTest (gałąź src/test/java), należy ją usunąć, gdyż będzie ona powodowała niepowodzenie na etapie test potoku CI. Klasa ta służy do wykonywania testów integracyjnych, którymi nie zajmujemy się w ramach niniejszego zadania (testy integracyjne będą omawiane na innych przedmiotach). Po skonfigurowaniu mechanizmu ciągłej integracji należy przejść na podstronę Pipelines, a następnie wybrać pierwszą pozycję na liście, aby sprawdzić szczegóły realizowanego potoku CI. Potok jest uruchamiany automatycznie po każdej zmianie w repozytorium (commit/push). W efekcie każda wersja projektu, która trafia do repozytorium, jest automatycznie testowana, budowana do postaci dystrybucyjnej i może być wdrożona na serwer testowy i/lub produkcyjny. Po poprawnym zakończeniu wszystkich zdefiniowanych etapów, potok powinien wyglądać następująco: Jeśli projekt zostanie poprawnie zbudowany na serwerze, bieżącą wersję w gałęzi master należy opatrzyć tagiem v1.0. Służy do tego polecenie git tag lub pozycja Team > Branch/Tag > Create Tag w menu środowiska Netbeans lub przycisk + > New tag w serwisie GitLab. Student, który został zaproszony do projektu, pobiera repozytorium na swoją stację roboczą (polecenie git clone lub Team > Git > Clone w środowisku Netbeans). Student, który importował kod do repozytorium, aktualizuje swoją kopię roboczą (polecenie git pull lub Team > Remote > Pull w środowisku Netbeans). Następnie należy utworzyć nową gałąź rozwojową o nazwie devel (polecenie git branch lub Team > Branch/Tag > Create Branch w Netbeansie lub + > New branch w serwisie GitLab). Po tej operacji należy przejść do sekcji Issues w serwisie GitLab i dodać zgłoszenia opisujące nowe funkcjonalności zadane przez prowadzącego. Do każdego zgłoszenia powinien zostać przypisany jeden z członków zespołu (pole Assignee w formularzu). W kolejnym kroku każdy z członków zespołu tworzy własną gałąź w repozytorium (na podstawie gałęzi devel), w której implementowana będzie funkcjonalność przypisana do danego studenta. Po tej operacji każdy ze studentów przełącza swoją kopię roboczą na własną gałąź (polecenie git checkout lub Team > Branch/Tag > Switch to Branch w Netbeansie). Następnie członkowie zespołu implementują nowe elementy aplikacji i commitują zmiany do swoich gałęzi. W. Korłub 6
Gdy nowe funkcjonalności zostaną zaimplementowane, zmiany wprowadzone w gałęziach poszczególnych studentów należy scalić do gałęzi devel. Jeśli nowa wersja projektu w gałęzi devel zostanie poprawnie zbudowana na serwerze CI, to zmiany z gałęzi devel można scalić do gałęzi master. Ostatnim krokiem jest oznaczenie końcowej wersji projektu w gałęzi master tagiem v1.1. Punktacja W ramach laboratorium oceniana jest praca całego zespołu wszyscy jego członkowie otrzymują taką samą liczbę punktów. Kryteria punktacji są następujące: prawidłowe skonfigurowanie mechanizmu ciągłej integracji 1 pkt, wypełnienie zgłoszeń w sekcji Issues serwisu GitLab z poprawnym przypisaniem członków zespołu do zadań 1 pkt, realizacja dodatkowych funkcjonalności aplikacji 1 pkt, prawidłowe wykorzystanie gałęzi w repozytorium git 2 pkt, o powinny być widoczne gałęzie: master, devel oraz po jednej gałęzi dla każdej nowej funkcjonalności projektu, o każdy commit do repozytorium powinien być opisany adekwatnym komunikatem. W. Korłub 7