• 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:

1. Wejdź do ustawień projektu lub grupy.
2. Wybierz zakładkę „Webhooks”.
3. W polu URL wpisz adres URL endpointu webhooka.
4. Jeśli potrzebujesz uwierzytelniania, wpisz tajny token w polu „Secret token”.
5. Wybierz zdarzenia, które mają wywoływać webhook.
6. Opcjonalnie, możesz wyłączyć weryfikację SSL, zaznaczając odpowiednie pole.
7. 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:

1. Wejdź do ustawień projektu lub grupy.
2. Wybierz zakładkę „Webhooks”.
3. W polu URL wpisz pełny URL webhooka.
4. Zaznacz opcję „Mask portions of URL”.
5. W polu „Sensitive portion of URL” wpisz fragment URLa, który chcesz zasłonić.
6. 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:

1. Wejdź do ustawień projektu lub grupy.
2. Wybierz zakładkę „Webhooks”.
3. Przewiń do listy skonfigurowanych webhooków.
4. Z rozwijanego menu „Test” wybierz rodzaj zdarzenia, które chcesz przetestować.
5. 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:

1. Wejdź do ustawień projektu lub grupy.
2. Wybierz zakładkę „Webhooks”.
3. 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:

![image](/uploads/$sha/image.png)

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:

![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)

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.

Artykuł Przewodnik po pracy z webhookami w GitLabie: kompletny poradnik pochodzi z serwisu TheForceCode - centrum wiedzy.