Jak wdrożyć CI/CD na własnym serwerze

Automatyzacja procesu wytwarzania oprogramowania stała się jednym z najważniejszych elementów nowoczesnego podejścia do pracy zespołów developerskich. Wdrożenie **CI/CD** na własnym serwerze pozwala nie tylko uniezależnić się od zewnętrznych usług, ale także zachować pełną kontrolę nad kodem, infrastrukturą i procesem dostarczania. Poniższy artykuł krok po kroku przeprowadzi przez projektowanie architektury, dobór narzędzi, konfigurację środowiska, bezpieczeństwo oraz praktyczne przykłady potoków ciągłej integracji i dostarczania.

Podstawy i architektura własnego CI/CD

CI/CD, czyli Continuous Integration oraz Continuous Delivery/Deployment, to praktyki polegające na częstym integrowaniu zmian w kodzie oraz automatycznym testowaniu i dostarczaniu ich na środowiska docelowe. Kluczową ideą jest minimalizacja ryzyka poprzez małe, powtarzalne i przewidywalne kroki zamiast rzadkich, dużych wdrożeń.

Na własnym serwerze rolę platformy CI/CD może pełnić np. Jenkins, GitLab CI, Drone CI, Gitea z Actions, Woodpecker, a nawet autorski zestaw skryptów. Niezależnie od wyboru, architektura zwykle składa się z kilku podobnych elementów:

Repozytorium kodu (Git) – centralne miejsce przechowywania źródeł, historii zmian, gałęzi i znaczników.
Serwer CI/CD – usługa nasłuchująca zmian w repozytorium (webhooki) i uruchamiająca zdefiniowane zadania (pipelines).
Agenty/workerzy – procesy wykonujące realne zadania: budowę, testy, deployment, skanowanie bezpieczeństwa.
Rejestr obrazów (np. Docker Registry) lub repozytorium artefaktów – miejsce przechowywania wyników budowania.
Środowiska docelowe – serwery testowe, staging, produkcja, na które pipeline wysyła nowe wersje aplikacji.

Własny serwer oznacza, że wszystkie powyższe elementy działają na maszynach zarządzanych samodzielnie – w serwerowni, w chmurze prywatnej lub na VPS. To podejście daje rozbudowane możliwości konfiguracji i optymalizacji, ale wymaga świadomych decyzji architektonicznych.

Najważniejsze korzyści z samodzielnego hostowania CI/CD:

Pełna kontrola nad danymi – kod, logi, artefakty i konfiguracja nie opuszczają infrastruktury.
Elastyczne dostosowanie środowiska do specyfiki projektu (niestandardowe biblioteki, wymagające buildy, specjalne zależności systemowe).
Możliwość integracji z wewnętrznymi systemami, do których nie chcemy wystawiać dostępu z zewnątrz.
Przejrzyste koszty – zamiast rozliczeń za minuty buildów płacimy za zasoby serwerowe, którymi zarządzamy samodzielnie.

Trzeba jednak liczyć się z obowiązkiem utrzymania infrastruktury, aktualizacjami, kopią zapasową i dbaniem o bezpieczeństwo. Zanim zostanie uruchomione pierwsze zadanie CI/CD, warto zaplanować podstawową topologię.

Przykładowy, prosty schemat:

Jeden serwer z zainstalowanym systemem Linux (np. Ubuntu Server LTS).
Na tym samym serwerze: Git (np. Gitea) oraz serwer CI (np. Jenkins).
Docker jako warstwa uruchamiania buildów i izolacji środowisk.
Lokalny rejestr Docker lub serwer do przechowywania artefaktów.

W większych organizacjach te funkcje są rozdzielane na wiele maszyn, z dodatkowymi komponentami (np. serwer do logowania i monitoringu), ale zrozumienie powyższej, uproszczonej architektury jest wystarczającym punktem wyjścia.

Dobór narzędzi i przygotowanie serwera

Wdrożenie CI/CD zaczyna się od decyzji: jakie narzędzia będą fundamentem systemu. Najczęściej rozważane są:

Jenkins – rozbudowane narzędzie z ogromnym ekosystemem wtyczek, dobrze sprawdza się w środowiskach samohostowanych.
GitLab CE + GitLab CI – kompletny pakiet: repozytorium, zarządzanie issue, pipeline’y, rejestr kontenerów, runnerzy.
Gitea + Actions/Drone/Woodpecker – lekka alternatywa dla GitLaba, dobra na mniejsze projekty lub środowiska z ograniczonymi zasobami.

Wybór powinien wynikać z wielkości projektów, znajomości narzędzi w zespole, a także wymagań w zakresie integracji. Dla wielu małych i średnich zespołów wystarczające będzie zestawienie Gitea + Drone lub GitLab CE z wbudowanym CI.

Przed instalacją narzędzi należy przygotować sam serwer:

Wybrać dystrybucję (najczęściej Ubuntu Server LTS, Debian lub CentOS/AlmaLinux).
Skonfigurować dostęp SSH (logowanie kluczami, wyłączenie prostego logowania hasłem, ograniczenie użytkowników).
Zaktualizować system i zainstalować podstawowe pakiety: git, curl, ufw/firewalld, narzędzia sieciowe.
Utworzyć dedykowanego użytkownika na usługi CI/CD (np. jenkins, gitlab, ci-runner).

Bez względu na wybraną platformę, praktycznie zawsze przydatne będzie użycie Dockera lub innej technologii kontenerowej. Kontenery upraszczają utrzymanie środowiska, umożliwiają wykorzystanie gotowych obrazów i łatwe odtwarzanie konfiguracji.

Przykład instalacji Dockera na Ubuntu:

Dodanie oficjalnego repozytorium Docker.
Instalacja pakietów docker-ce, docker-ce-cli, containerd.io.
Dodanie użytkownika CI do grupy docker.

Po stronie sieci należy zadbać o odpowiednie porty (HTTPS dla interfejsu web, SSH do repozytorium, porty runnerów) oraz o prawidłowe rekordy DNS, by serwer był dostępny pod stałą domeną.

Warto także od razu przygotować miejsce na logi i artefakty. Z uwagi na ich rozmiar dobrze jest oddzielić partycję lub wolumen dyskowy, a także przewidzieć mechanizmy rotowania logów i czyszczenia starych buildów.

Instalacja i konfiguracja podstawowych komponentów

Po przygotowaniu serwera można przystąpić do instalacji podstawowych komponentów CI/CD. Przykładowy zestaw to:

Serwer Git (np. Gitea lub GitLab CE).
Jenkins lub wbudowany silnik CI (GitLab CI).
Rejestr Docker (opcjonalnie w pierwszym etapie, ale bardzo przydatny przy mikrousługach).

Instalacja Gitea często sprowadza się do pobrania binarki lub użycia obrazu kontenera. Po pierwszym uruchomieniu kreator webowy pozwala zdefiniować bazę danych, ścieżkę do repozytoriów, użytkownika administracyjnego. GitLab CE zwykle instalowany jest z paczki omnibus, która automatycznie konfiguruje wiele usług (Redis, PostgreSQL, Nginx) i wystawia panel webowy do dalszej konfiguracji.

Konfiguracja repozytorium powinna uwzględniać:

Wymuszanie użycia SSH lub HTTPS z certyfikatem (np. Let’s Encrypt).
Strategię pracy z gałęziami: główna, deweloperska, gałęzie funkcjonalne, release, hotfix.
Uprawnienia dla zespołów: kto może merge’ować, kto zatwierdza pull/merge requesty.

Instalacja serwera CI, np. Jenkins, zazwyczaj polega na dodaniu repozytorium, instalacji pakietu i uruchomieniu usługi. Po pierwszym wejściu do panelu konfiguruje się użytkownika administratora, podstawowe wtyczki oraz lokalizację JDK, Maven, Gradle czy innych narzędzi buildowych.

Kluczowym etapem jest integracja między repozytorium a serwerem CI. W praktyce oznacza to skonfigurowanie:

Webhooków – repozytorium informuje serwer CI o nowych commitach i merge’ach.
Tokenów dostępowych – serwer CI może pobierać kod z repozytorium i zgłaszać statusy buildów.
Uprawnień – odpowiednie role i klucze SSH dla maszyn wykonawczych.

W przypadku GitLab CI integracja jest wbudowana, natomiast przy połączeniu Gitea + Jenkins trzeba utworzyć osobny token API, skonfigurować po stronie Gitea adres serwera Jenkins jako endpoint webhooka oraz po stronie Jenkins odpowiednie zadania typu multibranch lub pipeline, które będą reagowały na zdarzenia z Gita.

Następnie definiuje się agentów – mogą oni działać na tym samym serwerze lub na zewnętrznych maszynach. Agenty odpowiedzialne są za wykonanie realnych kroków pipeline: pobranie kodu, zbudowanie, testy, deployment. Warto rozdzielić agentów według zadań (np. agenty z dużą ilością RAM do kompilacji, inne do testów integracyjnych).

Tworzenie potoków CI – budowanie, testy i jakość

Dobrze zaprojektowany pipeline CI jest sercem całego systemu. Powinien być deklaratywny (zapisany w pliku w repozytorium), łatwy do zrozumienia, szybki w działaniu i powtarzalny. Dla większości projektów można wyróżnić podstawowe etapy:

Pobranie kodu z repozytorium.
Instalacja zależności.
Budowanie artefaktów (binarki, obrazy Docker, paczki).
Uruchomienie testów jednostkowych.
Uruchomienie testów integracyjnych lub e2e (o ile możliwe).
Analiza jakości (linting, skanowanie bezpieczeństwa, analiza statyczna).

W pliku konfiguracyjnym (np. Jenkinsfile, .gitlab-ci.yml) definiuje się poszczególne joby, ich zależności i warunki wywołania. Ważne jest, by unikać powielania logiki i konfigurować wspólne kroki (np. instalacja zależności) jako współdzielone fragmenty lub szablony.

Przykład podstawowego pipeline dla aplikacji webowej:

Stage: checkout – pobranie źródeł.
Stage: build – kompilacja, pakowanie, budowa obrazu kontenera.
Stage: test – testy jednostkowe i integracyjne.
Stage: quality – analiza statyczna i raportowanie metryk.

Ważną praktyką jest nadawanie pipeline’om deterministyczności – ten sam commit powinien zawsze dawać ten sam wynik, niezależnie od tego, kiedy i na którym agencie jest budowany. Osiąga się to poprzez precyzyjne wersjonowanie zależności, użycie kontenerów jako środowiska uruchomieniowego oraz unikanie losowości w testach.

Dobrym nawykiem jest także wczesne i konsekwentne włączanie testów. Nawet prosta paczka testów jednostkowych znacząco zmniejsza ryzyko wprowadzenia regresji. Dla projektów backendowych warto przewidzieć testy integracyjne z bazą danych (np. przy użyciu testcontainers), a w projektach frontendowych – testy e2e w przeglądarce uruchamiane na dedykowanym agencie lub w kontenerze.

Kolejnym elementem CI jest analiza jakości: lintery, formatowanie kodu, narzędzia typu SonarQube. Na własnym serwerze można uruchomić serwer SonarQube w kontenerze, a następnie każdy pipeline będzie wysyłał do niego raporty z analizy. Wyniki mogą być używane jako kryterium akceptacji merge requestów (np. blokowanie scalania, gdy jakość spada poniżej ustalonego progu).

Rezultatem działania CI są artefakty: zbudowane paczki, obrazy kontenerów, raporty testów, logi. Trzeba przewidzieć, jak długo będą przechowywane oraz jak będą identyfikowane (np. poprzez numer builda, commit hash, tag wersji). To ułatwi późniejsze wdrożenia i ewentualne roll-backi.

Projektowanie i wdrażanie procesu CD

CD, czyli ciągłe dostarczanie lub wdrażanie, jest naturalnym przedłużeniem CI. Tu również główną rolę odgrywa pipeline, ale zakres odpowiedzialności rozszerza się na zarządzanie środowiskami. Na własnym serwerze można wdrażać aplikacje na kilka sposobów:

Bezpośrednie kopiowanie artefaktów na serwer aplikacyjny (np. SCP, rsync, Ansible).
Wdrożenia kontenerowe – uruchamianie nowych wersji jako kontenerów Docker lub w Kubernetes.
Rolling update lub blue-green deployment – stopniowa wymiana wersji aplikacji w sposób minimalizujący przestoje.

Przy pierwszym wdrożeniu często wybiera się najprostszy scenariusz: pipeline buduje aplikację, pakuje ją i wysyła na serwer stagingowy, gdzie jest uruchamiana. Kolejny etap to wdrożenie na produkcję, zwykle po ręcznej akceptacji (tzw. manual gate) lub po dodatkowych testach automatycznych.

Projektując CD, należy odpowiedzieć na kilka pytań:

Jakie środowiska będą obsługiwane (dev, test, staging, prod)?
Jak będzie wyglądał przepływ zmian między środowiskami (promocja artefaktów, tagowanie wersji)?
Czy wdrożenie na produkcję ma być całkowicie automatyczne, czy wymaga ręcznego potwierdzenia?
W jaki sposób wykonamy roll-back w razie problemów po wdrożeniu?

Dla prostszych aplikacji wystarcza przywrócenie poprzedniego artefaktu lub obrazu kontenera. W pipeline warto więc zachować historię kilku ostatnich wersji oraz mechanizm szybkiego przełączenia. W przypadku wdrożeń kontenerowych przydatne jest trzymanie definicji usług w plikach konfiguracyjnych (Docker Compose, manifesty Kubernetes), które również podlegają wersjonowaniu w Git.

Automatyczne wdrożenia na produkcję (continuous deployment) niosą ze sobą ryzyko, jeśli nie ma dobrej kultury testów i monitoringu. Dlatego wiele zespołów decyduje się na continuous delivery – pipeline buduje i testuje wszystko automatycznie, ale samo wdrożenie na produkcję wymaga świadomej decyzji (np. kliknięcia w panelu serwera CI).

W obu przypadkach warto stosować parametryzację – ten sam pipeline może wdrażać różne gałęzie na różne środowiska, używając innych zmiennych (adresów baz danych, kluczy API, parametrów skalowania). Kluczowe jest rozdzielenie konfiguracji środowiska od kodu aplikacji, tak by zmiany w infrastrukturze były świadome i możliwe do śledzenia.

Bezpieczeństwo, tajne dane i dostęp do zasobów

Na własnym serwerze odpowiedzialność za bezpieczeństwo spoczywa całkowicie na właścicielu systemu. Dotyczy to zarówno infrastruktury (firewall, aktualizacje, backup), jak i procesów CI/CD. W pipeline’ach bardzo często pojawiają się dane wrażliwe: klucze do serwerów, hasła do baz danych, tokeny dostępowe do zewnętrznych API.

Podstawową zasadą jest oddzielenie kodu od tajnych danych. Hasła i klucze nie powinny pojawiać się w repozytorium w formie jawnej. Zamiast tego używa się:

Wbudowanych mechanizmów sekretów w narzędziu CI/CD (np. GitLab CI variables, Jenkins Credentials).
Zewnętrznych sejfów, takich jak HashiCorp Vault lub inne menedżery kluczy.
Szyfrowanych plików konfiguracyjnych, których odszyfrowanie następuje wyłącznie w bezpiecznym etapie pipeline.

Kolejnym ważnym aspektem jest nadawanie minimalnych, niezbędnych uprawnień. Agenty CI nie powinny mieć dostępu do całej infrastruktury z uprawnieniami administratora, jeśli nie jest to konieczne. Zamiast głównego klucza SSH do serwera produkcyjnego lepiej użyć osobnego konta z ograniczonym zakresem działań (np. możliwe tylko wykonanie konkretnych poleceń, brak uprawnień do zmiany konfiguracji systemu).

Ważne jest również kontrolowanie, kto w zespole może modyfikować pipeline’y. Błąd w skrypcie lub złośliwa zmiana może prowadzić do wycieku sekretów albo uszkodzenia środowiska. Zmiany konfiguracji CI/CD powinny przechodzić przez code review i być wersjonowane tak samo jak kod aplikacji.

Od strony systemowej nie wolno zapominać o:

Regularnym aktualizowaniu oprogramowania serwera i narzędzi (system, Docker, serwer CI, Git).
Konfiguracji firewall (otwarte wyłącznie niezbędne porty, segmentacja sieci).
Szyfrowaniu ruchu (HTTPS, SSH, zabezpieczenie API narzędzi CI/CD).
Monitoringu logów pod kątem prób nieautoryzowanego dostępu.

Bezpieczeństwo warto traktować jako stały element procesu CI/CD. Do pipeline’ów można włączyć automatyczne skanowanie zależności pod kątem podatności, statyczną analizę bezpieczeństwa kodu oraz testy dynamiczne na środowiskach testowych. Dzięki temu ryzyko wdrożenia podatnej wersji aplikacji jest istotnie zmniejszone.

Monitoring, logowanie i utrzymanie infrastruktury CI/CD

System CI/CD jest kluczowy dla całego cyklu życia oprogramowania. Jego niedostępność szybko paraliżuje pracę zespołu. Dlatego niezbędne jest traktowanie go jak elementu produkcyjnej infrastruktury: z monitoringiem, alertami, kopią zapasową i planem odtwarzania awaryjnego.

Podstawą jest zbieranie logów:

Logi narzędzia CI (Jenkins, GitLab Runner, itp.).
Logi serwerów aplikacyjnych, na które następuje deployment.
Logi systemowe (syslog, journald).

Logi warto centralizować w jednym miejscu (np. ELK/EFK stack, Graylog), aby możliwe było szybkie wyszukiwanie i korelowanie zdarzeń, zwłaszcza podczas analizy błędów pipelinów i problemów wdrożeniowych. Następnym krokiem jest monitoring metryk: obciążenie CPU, pamięci, dysku, liczba uruchamianych zadań, czas trwania buildów, wykorzystanie miejsca na artefakty.

Systemy takie jak Prometheus z Grafaną lub inne rozwiązania monitorujące pozwalają zbudować przejrzyste panele i ustawić alerty (e-mail, komunikatory) w razie przekroczenia progów. Dla stabilności CI/CD istotne jest także planowanie pojemności – liczby agentów, miejsca na dysku, przepustowości sieci.

Kolejnym elementem utrzymania jest backup. Własny serwer CI/CD przechowuje wiele krytycznych informacji: konfigurację pipeline’ów, historię buildów, artefakty, repozytoria. Należy zdefiniować politykę kopi zapasowych:

Jak często wykonywany jest backup (codziennie, kilka razy dziennie)?
Jak długo przechowywane są kopie (np. 30, 90 dni)?
Gdzie są przechowywane (inna lokalizacja, zaszyfrowane miejsce w chmurze)?
Jak wygląda procedura przywracania (testowanie odtwarzania w kontrolowanych warunkach)?

Bez okresowego sprawdzania procesu odtwarzania, backup jest jedynie iluzją bezpieczeństwa. Warto przeprowadzać testy: odtworzenie serwera CI/CD z kopii na innym hoście i sprawdzenie, czy pipeline’y działają poprawnie.

Utrzymanie obejmuje także planowanie aktualizacji narzędzi. Wprowadzenie nowych wersji Jenkins, GitLab czy Docker może mieć wpływ na pipeline’y, dlatego przed aktualizacją produkcyjnego środowiska dobrze jest posiadać serwer testowy, na którym możliwe jest sprawdzenie kompatybilności. Dobrą praktyką jest dokumentowanie zmian i ich wpływu, by w razie problemów móc szybko wrócić do stabilnej wersji.

Przykładowa ścieżka wdrożenia i dobre praktyki

Aby przełożyć powyższe koncepcje na praktykę, można przyjąć przykładowy plan wdrożenia CI/CD na własnym serwerze dla średniej aplikacji webowej:

Krok 1: Przygotowanie serwera – instalacja systemu, konfiguracja SSH, firewall, Docker.
Krok 2: Instalacja serwera Git (Gitea lub GitLab CE) i przeniesienie repozytorium.
Krok 3: Instalacja platformy CI (np. Jenkins) i połączenie jej z repozytorium przez webhooki.
Krok 4: Zdefiniowanie pierwszego prostego pipeline – checkout + build + test jednostkowy.
Krok 5: Rozszerzenie pipeline o testy integracyjne i analizę jakości.
Krok 6: Dodanie etapu deploymentu na środowisko testowe.
Krok 7: Wprowadzenie ręcznie kontrolowanego deploymentu na produkcję.
Krok 8: Zabezpieczenie sekretów, konfiguracja backupu, monitoringu i logowania.

Na każdym etapie warto angażować zespół developerski, DevOps i osoby odpowiedzialne za bezpieczeństwo. Dobre praktyki, które znacznie ułatwiają życie w dalszej perspektywie:

Pisanie pipeline’ów w sposób modułowy – wspólne kroki jako funkcje, szablony, biblioteki.
Umieszczanie definicji pipeline’ów w repozytorium, obok kodu aplikacji.
Wymuszanie code review nie tylko dla kodu biznesowego, ale także dla zmian w konfiguracji CI/CD.
Stopniowe zwiększanie zakresu automatyzacji, zamiast próby zautomatyzowania wszystkiego od razu.
Regularne przeglądy i refaktoryzację pipeline’ów, aby usuwać przestarzałe kroki i przyspieszać działanie.

Dobrze wdrożony system CI/CD na własnym serwerze staje się fundamentem pracy zespołu. Pozwala szybko reagować na zmiany wymagań, skraca czas dostarczania funkcji do użytkowników i ułatwia utrzymanie wysokiej jakości kodu. Wymaga to jednak systematycznego podejścia do architektury, bezpieczeństwa i utrzymania, a także kultury współpracy opartej na automatyzacji i transparentności procesów.