Ten wpis jest uzupełnieniem artykułu Ciągła Integracja: anioł stróż dobrego programisty, gdzie obiecałam pokazać konfigurację procesu budowania na konkretnym przykładzie serwera Atlassian Bamboo.

Co jest potrzebne? Parę słów na temat konfiguracji serwera i agentów

Żeby zdefiniować proces budowania przy użyciu Bamboo musimy mieć dostęp do:

1. Serwera Bamboo, który będzie zarządzał naszymi procesami budowania (inaczej buildami lub planami budowania).
2. Agentów Bamboo, czyli serwerów roboczych, które będą realizowały zadania zlecone przez Serwer Bamboo.

Kod serwera i agentów jest napisany w Javie. Serwery robocze, które chcą pełnić rolę agentów Bamboo i przyjmować zadania związane z procesem budowania, muszą zarejestrować się na serwerze.

Bamboo można, po wykupieniu licencji, zainstalować na własnym serwerze – z taką instalacją mam do czynienia na co dzień w pracy. Druga możliwość to skorzystanie z chmury firmy Atlassian. Wszystkie użyte w tym wpisie zrzuty ekranu pochodzą z wersji demonstracyjnej w chmurze (Bamboo Cloud). Główny serwer Bamboo działa wówczas w chmurze firmy Atlassian, natomiast agentów (serwery robocze) musisz uruchomić w chmurze Amazon EC2 w oparciu o obraz systemu dostarczony przez Atlassiana. Architekturę tego rozwiązania przedstawia poniższy rysunek.

Przy okazji drobna uwaga z kategorii troubleshooting: spędziłam parę godzin na próbach zrozumienia, dlaczego, mimo że moja instancja w chmurze EC2 bez problemu uruchamia się na żądanie serwera, nie realizuje żadnych wyznaczonych przez serwer zadań. Wreszcie okazało się, że odpowiedni obraz systemu z zainstalowanym agentem Bamboo jest dostępny tylko, jeśli jako lokalizację wybiorę region „US East (N. Virginia)”. W przeciwnym razie uruchamia się czysty system, niezdolny do współpracy z serwerem Bamboo. Być może od czasu moich prób problem został już rozwiązany.

Struktura Planu Bamboo

Proces budowania (ang. build) w świecie Bamboo jest określany mianem Planu Budowania (ang. Build Plan).

Tabela poniżej przedstawia elementy tworzące strukturę takiego planu.

Projekt	Może zawierać wiele planów. Wyświetla zbiorczy raport dla wszystkich swoich planów. Łączy się z innymi aplikacjami (np. JIRA do zarządzania zadaniami, Crucible do przeglądów kodu).
Plan	Dzieli się na Etapy, które wykonywane są sekwencyjnie. Definiuje domyślne repozytorium kodu. Określa, kiedy uruchomić proces budowania (wyzwalacze planu). Wysyła powiadomienia o wynikach kolejnych przebiegów. Pozwala definiować zmienne planu.
Etap (Stage)	Dzieli się na Porcje Pracy, wykonywane równolegle na wielu agentach jednocześnie (jeśli są dostępne). Etap (tj. wszystkie Porcje Pracy) musi się zakończyć powodzeniem, żeby wykonany został kolejny etap.
Porcja Pracy(Job )	Steruje wykonaniem listy Zadań, sekwencyjnie na tym samym agencie. Zbiera wymagania poszczególnych zadań, by wybrać agenta z odpowiednim zestawem umiejętności (ang. capabilities). Definiuje artefakty.
Zadanie (Task)	Zadanie to atomowa jednostka pracy, np. pobranie kodu z repozytorium, wywołanie polecenia Maven, uruchomienie skryptu.

Kompletna dokumentacja w języku angielskim jest dostępna na stronie https://confluence.atlassian.com/display/BAMBOO/Bamboo+Documentation+Home.

Utworzenie planu

Po pierwsze, w nowszych wersjach firma Atlassian ukryła przed użytkownikami link do Bamboo. Jeśli masz już konto w Jira/Bamboo Cloud lub dostęp do firmowej instalacji, oto jak przejść do panelu Bamboo:

Tworzenie planu:

Po utworzeniu planu możemy przejść do jego konfiguracji (na rysunku widać plan, który został już kilka razy uruchomiony – kolorowe ptaszki i wykrzykniki to historia jego kolejnych przebiegów):

Repozytorium kodu źródłowego

Plan ma na celu testowanie, budowanie i być może wdrażanie kodu źródłowego. Kod powinien być przechowywany w dobrze zorganizowanym repozytorium. Bamboo pozwala połączyć się ze wszystkimi najpopularniejszymi repozytoriami (w przypadku rozwiązań niestandardowych można jeszcze uciec się do pomocy pluginów). Repozytoria kodu źródłowego (w widocznym na rysunku przykładzie jest do publiczne repozytorium GitHub) konfiguruje się w zakładce Repositories:

Wyzwalacze

Wspomniałam w poprzednim wpisie, że każdy proces budowania ma swoje wyzwalacze. Możesz chcieć uruchamiać go ręcznie, automatycznie o określonej porze, albo po zmianie w wybranym repozytorium kodu. Jeśli zakończyłeś już konfigurację repozytoriów, możesz przejść do zakładki Triggers i tam zdefiniować wyzwalacze:

Ręczne uruchomienie planu przez wyznaczone osoby (zakładka Permissions pozwala na definicję uprawnień) zawsze jest możliwe, dlatego tej opcji nie ma na rozwijanej liście. Do dyspozycji masz: odpytywanie repozytorium o zmiany (sam wyznaczasz interwał dla tych zapytań), reakcję na sygnał z repozytorium, planowanie w oparciu o składnię cron oraz możliwość prostszego wskazania konkretnej godziny, o której plan ma zostać wykonany.

Powiadomienia

Skoro wiesz już, kiedy będzie uruchamiany plan, możesz podjąć decyzję kto, kiedy i jakim kanałem ma być powiadamiany o jego wynikach. Podstawowe źródło informacji to oczywiście raport widoczny poprzez interfejs www serwera,  gdzie wyniki odpowiednich planów „palą się” na czerwono bądź zielono. Warto wprowadzić wśród programistów dyscyplinę zerkania tam przynajmniej rano, po przyjściu do pracy. Oprócz tego możesz jednak stworzyć proste reguły powiadamiania konkretnych osób – np. mailem – o powodzeniu bądź niepowodzeniu procesu. Służy do tego zakładka Notifications.

Dobra rada – nie przesadzaj z powiadomieniami, ponieważ w końcu programiści przekierują je do katalogu spam. Informuj tylko te osoby, które naprawdę powinny wiedzieć o awarii lub samym fakcie uruchomienia danego planu.

Tworzenie etapu (Stage)

Domyślnie plan składa się z jednego etapu (Default Stage). Jeśli etapów będzie więcej, zostaną wykonane sekwencyjnie, przy czym niepowodzenie jednego z etapów zatrzyma wykonanie kolejnych. Dodatkowe etapy możesz tworzyć, korzystając z przycisku Create stage w zakładce Stages.

Tworzenie porcji pracy (Job)

Etap składa się z jednej lub więcej porcji pracy. Na powyższym rysunku widać etap zawierający dwie porcje pracy (Job1 i Job2) oraz możliwość dodania kolejnych (Add Job).

Uwaga! – porcje pracy są wykonywane równolegle; ich kolejność na liście nie ma najmniejszego znaczenia (Bamboo sortuje je alfabetycznie). Jeśli masz dyspozycji tylko jeden serwer roboczy, to oczywiście zostaną wykonane jedna po drugiej – w kolejności, na którą nie masz wpływu.

Każdej porcji pracy przypisane jest kilka właściwości:

1. Zadania (patrz niżej)
2. Artefakty (również niżej)
3. Wymagania

Wymagania to oczekiwania wobec serwera roboczego, który może podjąć się wykonania danej porcji pracy (i zdefiniowanych w niej zadań). Możemy zażądać dostępności określonych bibliotek, nałożyć wymagania na nazwę serwera itp. Wymaga to pewnej konfiguracji po stronie agenta Bamboo. Serwer Bamboo sprawdza wymagania w czasie rzeczywistym i od razu informuje, ile agentów potrafi wykonać daną porcję pracy.

W poniższym przykładzie żaden agent nie spełnia wymagań (zerowych), ponieważ nie została uruchomiona żadna instancja w chmurze 🙂

Tworzenie zadania (Task)

Zadanie to najmniejsza, atomowa jednostka pracy w planie Bamboo. Zadania są definiowane w ramach jednostek pracy i są wykonywane sekwencyjnie. Uwaga – niepowodzenia są raportowane na poziomie jednostek pracy: nie dostaniesz czytelnej informacji, które z zadań spowodowało problem (chyba że w dobrze zorganizowanych logach lub na postawie informacji o tym, który test nie przeszedł).

Bamboo predefiniuje wiele zadań. Pobranie danych z repozytorium, wykonanie budowania przy użyciu narzędzia takiego jak Maven – w takich sytuacjach musisz tylko wypełnić odpowiedni formularz, np. wskazując odpowiednie ze zdefiniowanych repozytoriów.

Poniższy zrzut ekranu przedstawia widok jednego z dwóch zadań w ramach jednostki pracy. Jest to predefiniowane zadanie pobrania kodu z repozytorium kodu źródłowego.

Jeżeli musisz zrobić coś niestandardowego – jak niezalecane specjalnie wysłanie przeprowadzonych przez Twój plan zmian w kodzie do repozytorium – możesz poszukać odpowiedniego pluginu (lub samodzielnie go napisać), albo użyć zadania Script, w którym samodzielnie napiszesz kod dla odpowiedniej powłoki w systemie operacyjnym agenta:

Artefakty

Artefakty, czyli dodatkowe produkty planu budowania, jak wspomniałam już wcześniej, są dostępne na etapie jednostek pracy (jobs), ale wygenerować je trzeba przy użyciu zadań. Kod przedstawiony na powyższym rysunku zapisuje do pliku wartość jednej ze zmiennych Bamboo (ich lista oraz zasady definiowania własnych są dostępne tutaj). Możemy oznaczyć ten plik jako artefakt planu. Artefakty można pobierać (także przez przeglądarkę) oraz współdzielić pomiędzy etapami (a w nowszych wersjach serwera również pomiędzy planami).

Oto, jak wygląda gotowy do pobrania artefakt:

Uwaga! – przy definiowaniu artefaktów należy pamiętać o tym, że ścieżkę do nich podaje się względem katalogu roboczego danej jednostki pracy. Jeśli korzystasz ze ścieżek bezwzględnych na serwerze, możesz sprawdzić wartość zmiennej bamboo.build.working.directory.

Testy

Testy mają kluczowe znaczenie dla całego procesu ciągłej integracji. Technicznie sprowadzają się jednak do zwykłego, predefiniowanego zadania Bamboo: odczytu wskazanego przez Ciebie (w katalogu roboczym) pliku JUnit/XML.

Troubleshooting (na podstawie własnych, bolesnych doświadczeń):

1. Jeśli w planie były nieprzechodzące testy, a w kolejnym przebiegu testów brak, Bamboo uzna to za błąd kompilacji.
2. Kilka wersji Bamboo przejawiało następujący błąd: katalog z wynikami testów nie był odświeżany, jeśli plan został wykonany „zbyt szybko”.
3. Jeśli chcesz dopuścić nieprzechodzące testy (np. na potrzeby TDD), musisz skorzystać z opcji dodania ich do kwarantanny.

Podsumowanie

Rysunek przedstawia podsumowanie kilku ostatnich przebiegów w planie budowania Bamboo, wraz z informacją o przyczynie uruchomienia planu i o liczbie testów:

Dla każdego z przebiegów możesz bardzo intuicyjnie doklikać się do informacji o testach, commitach do repozytorium i odpowiedzialnych za nie osobach. Wspominałam już o możliwości synchronizacji Bamboo z innymi produktami firmy Atlassian. Możesz, na przykład, utworzyć zadanie w Jirze w oparciu o nieudany przebieg:

Miłej zabawy!