Webhooki są istotnym elementem w integracji GitLab z innymi narzędziami. Pozwalają na automatyczne wywoływanie akcji w zewnętrznych aplikacjach w odpowiedzi na zdarzenia w repozytorium lub projekcie. W tym przewodniku przedstawimy kompletny poradnik dotyczący pracy z webhookami w GitLabie, włącznie z konfiguracją, maskowaniem URLi, weryfikacją tokenów, filtrowaniem zdarzeń i rozwiązywaniem problemów.
- Wprowadzenie do webhooków w GitLabie
- Konfiguracja webhooka w projekcie lub grupie
- Maskowanie wrażliwych części URLi webhooków
- Konfiguracja endpointu odbierającego webhooki
- Obsługa webhooków o niewłaściwym statusie
- Testowanie webhooków
- Tworzenie przykładowego endpointu odbierającego webhooki
- Weryfikacja payloadów przy użyciu tokena uwierzytelniającego
- Filtrowanie zdarzeń push według gałęzi
- Wyświetlanie URLi obrazów w ciele webhooka
- Dodatkowe narzędzia do inspekcji i testowania webhooków
- Rozwiazywanie problemów z webhookami
- Podsumowanie
Wprowadzenie do webhooków w GitLabie
Webhooki to niestandardowe wywołania HTTP, które można zdefiniować w GitLabie. Są one zazwyczaj wyzwalane przez konkretne zdarzenia, takie jak przesłanie kodu do repozytorium lub dodanie komentarza do zgłoszenia. Gdy zdarzenie wystąpi, aplikacja źródłowa wysyła żądanie HTTP pod adres URL webhooka skonfigurowanego w GitLabie. Akcje, które można podjąć w wyniku webhooka, są praktycznie nieograniczone. Na przykład można użyć webhooków do:
- Wywoływania zadań integracji ciągłej (CI)
- Aktualizowania zewnętrznych systemów do śledzenia problemów
- Aktualizowania kopii zapasowych repozytorium
- Wdrażania na serwer produkcyjny
- Wysyłania powiadomień na Slacka o nieudanych zadaniach
Konfiguracja webhooka w projekcie lub grupie
Aby skonfigurować webhooka dla projektu lub grupy w GitLabie, należy postępować zgodnie z poniższymi krokami:
- Wejdź do ustawień projektu lub grupy.
- Wybierz zakładkę „Webhooks”.
- W polu URL wpisz adres URL endpointu webhooka.
- Jeśli potrzebujesz uwierzytelniania, wpisz tajny token w polu „Secret token”.
- Wybierz zdarzenia, które mają wywoływać webhook.
- Opcjonalnie, możesz wyłączyć weryfikację SSL, zaznaczając odpowiednie pole.
- Kliknij „Dodaj webhook”.
Maskowanie wrażliwych części URLi webhooków
W przypadku, gdy w URLu webhooka występują wrażliwe dane, GitLab umożliwia ich zasłonięcie i zastąpienie skonfigurowanymi wartościami podczas wykonywania webhooka. Wrażliwe dane nie są rejestrowane i są szyfrowane w bazie danych. Aby zasłonić wrażliwe części URLa webhooka, wykonaj następujące kroki:
- Wejdź do ustawień projektu lub grupy.
- Wybierz zakładkę „Webhooks”.
- W polu URL wpisz pełny URL webhooka.
- Zaznacz opcję „Mask portions of URL”.
- W polu „Sensitive portion of URL” wpisz fragment URLa, który chcesz zasłonić.
- W polu „How it looks in the UI” wpisz wartość, która zastąpi zasłoniętą część URLa.
Konfiguracja endpointu odbierającego webhooki
Endpoint odbierający webhooki powinien być szybki i stabilny. Powolne lub niestabilne endpointy mogą zostać automatycznie wyłączone, aby zapewnić niezawodność systemu. W przypadku nieudanych webhooków może wystąpić duplikowanie zdarzeń. Endpointy powinny spełniać następujące zasady:
- Szybka odpowiedź z kodem statusu 200 lub 201.
- Unikanie długotrwałej obróbki webhooków w tym samym żądaniu. Zamiast tego, należy zaimplementować kolejkę do obsługi webhooków po ich otrzymaniu.
- Przygotowanie na obsługę zduplikowanych zdarzeń. W niektórych przypadkach to samo zdarzenie może być wysłane dwukrotnie. Aby temu zapobiec, endpoint musi być niezawodny, szybki i stabilny.
- Minimalizacja treści odpowiedzi. GitLab nie analizuje nagłówków ani treści odpowiedzi. Warto ograniczyć liczbę i rozmiar zwracanych nagłówków. Można również zwrócić puste ciało odpowiedzi webhooka.
- Zwracanie tylko błędów klienta (kody w zakresie 4xx), aby wskazać nieprawidłową konfigurację webhooka. Odpowiedzi w tym zakresie mogą spowodować automatyczne wyłączenie webhooków.
Obsługa webhooków o niewłaściwym statusie
W przypadku webhooków, które nie działają poprawnie, GitLab ma mechanizmy automatycznego wyłączania i ponownego włączania. Webhooki mogą być wyłączane z następujących powodów:
- Webhooki, które nie mogą nawiązać połączenia, są wyłączane ręcznie i muszą być ponownie włączone ręcznie.
- Webhooki, które zwracają kody odpowiedzi w zakresie 5xx, są tymczasowo wyłączane, jeśli występują błędy intermitentne. Pierwsze wyłączenie trwa jedną minutę, a kolejne wyłączenia są wydłużane, aż do maksymalnego czasu wyłączenia wynoszącego 24 godziny.
- Webhooki, które zwracają kody odpowiedzi w zakresie 4xx, są uważane za źle skonfigurowane i są wyłączane na stałe, dopóki nie zostaną ręcznie włączone.
- Aby ponownie włączyć wyłączone webhooki, należy wysłać testowe żądanie. Jeśli żądanie testowe powiedzie się, webhook zostanie ponownie włączony.
Testowanie webhooków
W celu sprawdzenia poprawności działania webhooka w GitLabie, można go ręcznie wywołać. Można również wysłać żądanie testowe, aby ponownie włączyć wyłączony webhook. Aby przetestować webhook, należy postępować zgodnie z poniższymi krokami:
- Wejdź do ustawień projektu lub grupy.
- Wybierz zakładkę „Webhooks”.
- Przewiń do listy skonfigurowanych webhooków.
- Z rozwijanego menu „Test” wybierz rodzaj zdarzenia, które chcesz przetestować.
- Możesz również przetestować webhook z poziomu jego strony edycji.
Tworzenie przykładowego endpointu odbierającego webhooki
Aby przetestować działanie webhooków w GitLabie, można użyć skryptu echo, który będzie wyświetlał treść żądania HTTP w konsoli. Aby skrypt działał poprawnie, należy mieć zainstalowany Ruby. Poniżej znajduje się przykładowy skrypt:
require 'webrick' server = WEBrick::HTTPServer.new(:Port => ARGV.first) server.mount_proc '/' do |req, res| puts req.body end trap 'INT' do server.shutdown end server.start
Aby uruchomić skrypt, należy zapisać go jako print_http_body.rb i uruchomić polecenie ruby print_http_body.rb w konsoli. Następnie można skonfigurować webhook w GitLabie, podając adres URL endpointu, na którym uruchomiono skrypt.
Weryfikacja payloadów przy użyciu tokena uwierzytelniającego
Aby zweryfikować, czy otrzymany payload webhooka jest autentyczny, można użyć tajnego tokenu. Token ten jest przesyłany w nagłówku HTTP X-Gitlab-Token. Endpoint webhooka może sprawdzić ten token w celu potwierdzenia, że żądanie jest prawidłowe. Aby skonfigurować weryfikację tokena, należy:
- Wejdź do ustawień projektu lub grupy.
- Wybierz zakładkę „Webhooks”.
- W polu „Secret token” wpisz tajny token, który zostanie użyty do weryfikacji payloadu.
Filtrowanie zdarzeń push według gałęzi
W GitLabie istnieje możliwość filtrowania zdarzeń push według gałęzi. Można użyć jednej z poniższych opcji:
- Wszystkie gałęzie: zdarzenia push z wszystkich gałęzi.
- Wzorzec wildcard: zdarzenia push z gałęzi, które pasują do wzorca wildcard (np. -stable lub production/).
- Wyrażenie regularne: zdarzenia push z gałęzi, które pasują do wyrażenia regularnego (np. ^(feature|hotfix)/).
Aby skonfigurować filtrowanie gałęzi dla projektu lub grupy, należy postępować zgodnie z instrukcjami w sekcji „Konfiguracja webhooka w GitLabie”.
Wyświetlanie URLi obrazów w ciele webhooka
URLi obrazów w ciele webhooka są automatycznie przekształcane na absolutne URL-e. Jeśli w treści webhooka znajduje się odwołanie do obrazu w postaci relatywnej, GitLab automatycznie przekształca je na URL absolutny. Na przykład, jeśli odwołanie do obrazu wygląda następująco:
A GitLab jest zainstalowany pod adresem gitlab.example.com, a projekt znajduje się pod adresem example-group/example-project, odwołanie to zostanie przekształcone na:
URL-e obrazów nie są przekształcane, jeśli:
- Już wskazują na URL-e HTTP, HTTPS lub protokołowe.
- Wykorzystują zaawansowane funkcje Markdown, takie jak etykiety linków.
Dodatkowe narzędzia do inspekcji i testowania webhooków
W celu inspekcji i testowania webhooków w GitLabie można skorzystać z różnych publicznych narzędzi. Oto kilka przykładów:
- Beeceptor https://beeceptor.com – narzędzie umożliwiające tworzenie tymczasowych punktów końcowych HTTPS i inspekcję przychodzących payloadów.
- Webhook.site https://webhook.site – narzędzie umożliwiające przeglądanie przychodzących payloadów webhooków.
- Można również skorzystać z narzędzi dostępnych w GitLabie, takich jak:
- GitLab Development Kit (GDK) – narzędzie umożliwiające rozwijanie webhooków lokalnie.
- Możliwość przeglądania ostatnio wywołanych payloadów webhooków w ustawieniach GitLab.
Rozwiązywanie problemów z webhookami
W przypadku problemów z webhookami w GitLabie można skorzystać z różnych narzędzi i funkcji dostępnych w systemie. Oto kilka przykładów:
- Przeglądanie ostatnio wywołanych webhooków w tabeli „Recent events” w ustawieniach projektu lub grupy.
- Sprawdzanie kodów odpowiedzi HTTP, które są wyświetlane jako zielone dla kodów z zakresu 200-299, czerwone dla pozostałych kodów oraz jako „internal error” dla nieudanych dostaw.
- Wyświetlanie szczegółów żądania webhooka, w tym nagłówków i treści żądania oraz odpowiedzi.
- Ponowne wysłanie żądania webhooka z tą samą zawartością.
Podsumowanie
W tym przewodniku przedstawiliśmy kompletny poradnik dotyczący pracy z webhookami w GitLabie. Omówiliśmy konfigurację webhooków, maskowanie wrażliwych danych, weryfikację payloadów, filtrowanie zdarzeń push i wiele innych aspektów. Dzięki tym informacjom będziesz w stanie skonfigurować webhooki w GitLabie i zintegrować je z innymi narzędziami w swoim procesie DevOps.