Webhooki s\u0105 istotnym elementem w integracji GitLab z innymi narz\u0119dziami. Pozwalaj\u0105 na automatyczne wywo\u0142ywanie akcji w zewn\u0119trznych aplikacjach w odpowiedzi na zdarzenia w repozytorium lub projekcie. W tym przewodniku przedstawimy kompletny poradnik dotycz\u0105cy pracy z webhookami w GitLabie, w\u0142\u0105cznie z konfiguracj\u0105, maskowaniem URLi, weryfikacj\u0105 token\u00f3w, filtrowaniem zdarze\u0144 i rozwi\u0105zywaniem problem\u00f3w.<\/p>\n
Webhooki to niestandardowe wywo\u0142ania HTTP, kt\u00f3re mo\u017cna zdefiniowa\u0107 w GitLabie. S\u0105 one zazwyczaj wyzwalane przez konkretne zdarzenia, takie jak przes\u0142anie kodu do repozytorium lub dodanie komentarza do zg\u0142oszenia. Gdy zdarzenie wyst\u0105pi, aplikacja \u017ar\u00f3d\u0142owa wysy\u0142a \u017c\u0105danie HTTP pod adres URL webhooka skonfigurowanego w GitLabie. Akcje, kt\u00f3re mo\u017cna podj\u0105\u0107 w wyniku webhooka, s\u0105 praktycznie nieograniczone. Na przyk\u0142ad mo\u017cna u\u017cy\u0107 webhook\u00f3w do:<\/p>\n
Aby skonfigurowa\u0107 webhooka dla projektu lub grupy w GitLabie, nale\u017cy post\u0119powa\u0107 zgodnie z poni\u017cszymi krokami:<\/p>\n
W przypadku, gdy w URLu webhooka wyst\u0119puj\u0105 wra\u017cliwe dane, GitLab umo\u017cliwia ich zas\u0142oni\u0119cie i zast\u0105pienie skonfigurowanymi warto\u015bciami podczas wykonywania webhooka. Wra\u017cliwe dane nie s\u0105 rejestrowane i s\u0105 szyfrowane w bazie danych. Aby zas\u0142oni\u0107 wra\u017cliwe cz\u0119\u015bci URLa webhooka, wykonaj nast\u0119puj\u0105ce kroki:<\/p>\n
Endpoint odbieraj\u0105cy webhooki powinien by\u0107 szybki i stabilny. Powolne lub niestabilne endpointy mog\u0105 zosta\u0107 automatycznie wy\u0142\u0105czone, aby zapewni\u0107 niezawodno\u015b\u0107 systemu. W przypadku nieudanych webhook\u00f3w mo\u017ce wyst\u0105pi\u0107 duplikowanie zdarze\u0144. Endpointy powinny spe\u0142nia\u0107 nast\u0119puj\u0105ce zasady:<\/p>\n
W przypadku webhook\u00f3w, kt\u00f3re nie dzia\u0142aj\u0105 poprawnie, GitLab ma mechanizmy automatycznego wy\u0142\u0105czania i ponownego w\u0142\u0105czania. Webhooki mog\u0105 by\u0107 wy\u0142\u0105czane z nast\u0119puj\u0105cych powod\u00f3w:<\/p>\n
W celu sprawdzenia poprawno\u015bci dzia\u0142ania webhooka w GitLabie, mo\u017cna go r\u0119cznie wywo\u0142a\u0107. Mo\u017cna r\u00f3wnie\u017c wys\u0142a\u0107 \u017c\u0105danie testowe, aby ponownie w\u0142\u0105czy\u0107 wy\u0142\u0105czony webhook. Aby przetestowa\u0107 webhook, nale\u017cy post\u0119powa\u0107 zgodnie z poni\u017cszymi krokami:<\/p>\n
Aby przetestowa\u0107 dzia\u0142anie webhook\u00f3w w GitLabie, mo\u017cna u\u017cy\u0107 skryptu echo, kt\u00f3ry b\u0119dzie wy\u015bwietla\u0142 tre\u015b\u0107 \u017c\u0105dania HTTP w konsoli. Aby skrypt dzia\u0142a\u0142 poprawnie, nale\u017cy mie\u0107 zainstalowany Ruby. Poni\u017cej znajduje si\u0119 przyk\u0142adowy skrypt:<\/p>\n
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\r\n<\/pre>\nAby uruchomi\u0107 skrypt, nale\u017cy zapisa\u0107 go jako print_http_body.rb i uruchomi\u0107 polecenie ruby print_http_body.rb w konsoli. Nast\u0119pnie mo\u017cna skonfigurowa\u0107 webhook w GitLabie, podaj\u0105c adres URL endpointu, na kt\u00f3rym uruchomiono skrypt.<\/p>\n
<\/a>Weryfikacja payload\u00f3w przy u\u017cyciu tokena uwierzytelniaj\u0105cego<\/h2>\n
Aby zweryfikowa\u0107, czy otrzymany payload webhooka jest autentyczny, mo\u017cna u\u017cy\u0107 tajnego tokenu. Token ten jest przesy\u0142any w nag\u0142\u00f3wku HTTP X-Gitlab-Token. Endpoint webhooka mo\u017ce sprawdzi\u0107 ten token w celu potwierdzenia, \u017ce \u017c\u0105danie jest prawid\u0142owe. Aby skonfigurowa\u0107 weryfikacj\u0119 tokena, nale\u017cy:<\/p>\n
\n
- Wejd\u017a do ustawie\u0144 projektu lub grupy.<\/li>\n
- Wybierz zak\u0142adk\u0119 „Webhooks”.<\/li>\n
- W polu „Secret token” wpisz tajny token, kt\u00f3ry zostanie u\u017cyty do weryfikacji payloadu.<\/li>\n<\/ol>\n
<\/a>Filtrowanie zdarze\u0144 push wed\u0142ug ga\u0142\u0119zi<\/h2>\n
W GitLabie istnieje mo\u017cliwo\u015b\u0107 filtrowania zdarze\u0144 push wed\u0142ug ga\u0142\u0119zi. Mo\u017cna u\u017cy\u0107 jednej z poni\u017cszych opcji:<\/p>\n
\n
- Wszystkie ga\u0142\u0119zie: zdarzenia push z wszystkich ga\u0142\u0119zi.<\/li>\n
- Wzorzec wildcard: zdarzenia push z ga\u0142\u0119zi, kt\u00f3re pasuj\u0105 do wzorca wildcard (np. -stable lub production\/).<\/li>\n
- Wyra\u017cenie regularne: zdarzenia push z ga\u0142\u0119zi, kt\u00f3re pasuj\u0105 do wyra\u017cenia regularnego (np. ^(feature|hotfix)\/).<\/li>\n<\/ul>\n
Aby skonfigurowa\u0107 filtrowanie ga\u0142\u0119zi dla projektu lub grupy, nale\u017cy post\u0119powa\u0107 zgodnie z instrukcjami w sekcji „Konfiguracja webhooka w GitLabie”.<\/p>\n
<\/a>Wy\u015bwietlanie URLi obraz\u00f3w w ciele webhooka<\/h2>\n
URLi obraz\u00f3w w ciele webhooka s\u0105 automatycznie przekszta\u0142cane na absolutne URL-e. Je\u015bli w tre\u015bci webhooka znajduje si\u0119 odwo\u0142anie do obrazu w postaci relatywnej, GitLab automatycznie przekszta\u0142ca je na URL absolutny. Na przyk\u0142ad, je\u015bli odwo\u0142anie do obrazu wygl\u0105da nast\u0119puj\u0105co:<\/p>\n
\r\n<\/pre>\nA GitLab jest zainstalowany pod adresem gitlab.example.com, a projekt znajduje si\u0119 pod adresem example-group\/example-project, odwo\u0142anie to zostanie przekszta\u0142cone na:<\/p>\n
\r\n<\/pre>\nURL-e obraz\u00f3w nie s\u0105 przekszta\u0142cane, je\u015bli:<\/p>\n
\n
- Ju\u017c wskazuj\u0105 na URL-e HTTP, HTTPS lub protoko\u0142owe.<\/li>\n
- Wykorzystuj\u0105 zaawansowane funkcje Markdown, takie jak etykiety link\u00f3w.<\/li>\n<\/ul>\n
<\/a>Dodatkowe narz\u0119dzia do inspekcji i testowania webhook\u00f3w<\/h2>\n
W celu inspekcji i testowania webhook\u00f3w w GitLabie mo\u017cna skorzysta\u0107 z r\u00f3\u017cnych publicznych narz\u0119dzi. Oto kilka przyk\u0142ad\u00f3w:<\/p>\n
\n
- Beeceptor https:\/\/beeceptor.com – narz\u0119dzie umo\u017cliwiaj\u0105ce tworzenie tymczasowych punkt\u00f3w ko\u0144cowych HTTPS i inspekcj\u0119 przychodz\u0105cych payload\u00f3w.<\/li>\n
- Webhook.site https:\/\/webhook.site – narz\u0119dzie umo\u017cliwiaj\u0105ce przegl\u0105danie przychodz\u0105cych payload\u00f3w webhook\u00f3w.<\/li>\n
- Mo\u017cna r\u00f3wnie\u017c skorzysta\u0107 z narz\u0119dzi dost\u0119pnych w GitLabie, takich jak:<\/li>\n
- GitLab Development Kit (GDK) – narz\u0119dzie umo\u017cliwiaj\u0105ce rozwijanie webhook\u00f3w lokalnie.<\/li>\n
- Mo\u017cliwo\u015b\u0107 przegl\u0105dania ostatnio wywo\u0142anych payload\u00f3w webhook\u00f3w w ustawieniach GitLab.<\/li>\n<\/ul>\n
<\/a>Rozwi\u0105zywanie problem\u00f3w z webhookami<\/h2>\n
W przypadku problem\u00f3w z webhookami w GitLabie mo\u017cna skorzysta\u0107 z r\u00f3\u017cnych narz\u0119dzi i funkcji dost\u0119pnych w systemie. Oto kilka przyk\u0142ad\u00f3w:<\/p>\n
\n
- Przegl\u0105danie ostatnio wywo\u0142anych webhook\u00f3w w tabeli „Recent events” w ustawieniach projektu lub grupy.<\/li>\n
- Sprawdzanie kod\u00f3w odpowiedzi HTTP, kt\u00f3re s\u0105 wy\u015bwietlane jako zielone dla kod\u00f3w z zakresu 200-299, czerwone dla pozosta\u0142ych kod\u00f3w oraz jako „internal error” dla nieudanych dostaw.<\/li>\n
- Wy\u015bwietlanie szczeg\u00f3\u0142\u00f3w \u017c\u0105dania webhooka, w tym nag\u0142\u00f3wk\u00f3w i tre\u015bci \u017c\u0105dania oraz odpowiedzi.<\/li>\n
- Ponowne wys\u0142anie \u017c\u0105dania webhooka z t\u0105 sam\u0105 zawarto\u015bci\u0105.<\/li>\n<\/ul>\n
<\/a>Podsumowanie<\/h2>\n
W tym przewodniku przedstawili\u015bmy kompletny poradnik dotycz\u0105cy pracy z webhookami w GitLabie. Om\u00f3wili\u015bmy konfiguracj\u0119 webhook\u00f3w, maskowanie wra\u017cliwych danych, weryfikacj\u0119 payload\u00f3w, filtrowanie zdarze\u0144 push i wiele innych aspekt\u00f3w. Dzi\u0119ki tym informacjom b\u0119dziesz w stanie skonfigurowa\u0107 webhooki w GitLabie i zintegrowa\u0107 je z innymi narz\u0119dziami w swoim procesie DevOps.<\/p>\n
\n