Otwórz wniosek DueReason z oznaczonego etykietą zgłoszenia lub PR na GitHubie
Dodaj etykietę do zgłoszenia lub pull requestu na GitHubie, a DueReason automatycznie otworzy podpisany wniosek o zatwierdzenie -- bez pollingu.
Aktualizacja · 7 min czytania
W skrócie
- Endpoint przychodzący z GitHuba wiąże jedno repozytorium i jedną etykietę z jedną akcją DueReason: dodanie tej etykiety do zgłoszenia lub pull requestu otwiera prawdziwy wniosek o zatwierdzenie, z podpisanym grantem i wpisem w rejestrze, a nie tylko powiadomienie.
- Konfiguracja to dwa kroki w przeciwnych kierunkach: najpierw tworzysz endpoint w konsoli DueReason, żeby dostać adres URL, a potem wklejasz ten adres i własny sekret webhooka w ustawieniach webhooków repozytorium na GitHubie.
- Szablon danych mapuje pola zdarzenia z GitHuba na własny payload akcji za pomocą placeholderów w stylu `{{issue.title}}`, więc otwarty wniosek niesie realne dane, a nie tylko odnośnik z powrotem do GitHuba.
- Identyfikator dostarczenia z GitHuba sprawia, że ponowiona próba nie tworzy drugiego wniosku, a dopasowują się wyłącznie zdarzenia `issues` i `pull_request` z akcją `labeled` -- usunięcie etykiety, komentarz czy każde inne zdarzenie są po cichu ignorowane.
- Linear i Jira to dwa kolejne źródła na tym samym schemacie: skonfigurowany klucz zespołu i docelowy status workflow (Linear), albo klucz projektu i docelowy status (Jira), otwierają wniosek zamiast repozytorium i etykiety. Jira nie ma nagłówka podpisu HMAC, więc jej endpoint uwierzytelnia współdzielony nagłówek-sekret.
Etykietowanie zgłoszenia lub pull requestu to w wielu zespołach już dziś sposób na oznaczenie "to wymaga decyzji" -- needs-approval, ship-it, budget-review. Endpoint przychodzący z GitHuba zamienia tę etykietę w prawdziwy wniosek o zatwierdzenie w DueReason w chwili, gdy zostaje dodana -- z podpisanym grantem i wpisem w rejestrze za decyzją, zamiast komentarza bota albo wiadomości na Slacku, o której ktoś musi pamiętać.
Co się właściwie dzieje
Każdy endpoint przychodzący wiąże jedno repozytorium GitHuba i jedną etykietę z jedną akcją DueReason. W chwili, gdy ktoś doda tę etykietę do zgłoszenia lub pull requestu w tym repozytorium, DueReason otwiera wniosek względem wybranej akcji, wypełniony danymi ze zdarzenia: tytuł w stylu GitHub: acme/widgets#42 labeled "needs-approval", powód wskazujący zgłoszenie lub PR z odnośnikiem z powrotem do GitHuba, oraz pola payloadu zmapowane przez Twój szablon. Od tego momentu to zwykły wniosek DueReason -- przechodzi przez workflow skonfigurowany dla tej akcji, trafia do wybranych zatwierdzających i kończy się tym samym podpisanym, jednorazowym grantem co każdy inny wniosek.
Najpierw skonfiguruj to w DueReason
W Ustawienia > Webhooki przychodzące, Dodaj endpoint pyta o cztery rzeczy: Repozytorium (owner/repo), Etykieta (dokładna etykieta GitHuba, która po dodaniu otwiera wniosek), Akcja (która akcja DueReason ma zostać otwarta, z listy akcji skonfigurowanych w Twojej organizacji) i Szablon danych -- JSON mapujący pola payloadu tej akcji na dane zdarzenia z GitHuba, na przykład { "title": "{{issue.title}}", "url": "{{issue.html_url}}" }. Wklejasz tu też Sekret webhooka GitHub: wartość, którą *sam* generujesz, a nie taką, którą wydaje DueReason -- dokładnie tę samą wartość wkleisz za chwilę do GitHuba, a DueReason nie pokaże jej ponownie po tym kroku.
Utworzenie endpointu zwraca jeden adres URL webhooka na Twojej własnej domenie, w formacie /api/webhooks/github-inbound/{endpointId}. Nic się nie uruchomi, dopóki ten adres nie zostanie zarejestrowany po stronie GitHuba.
Potem wskaż go w GitHubie
W ustawieniach repozytorium, Settings > Webhooks > Add webhook, wklej ten adres jako Payload URL, ustaw typ treści na application/json i wklej ten sam sekret, który przed chwilą wpisałeś w DueReason, jako sekret webhooka. Wybierz zdarzenia Issues i Pull requests (albo "Send me everything", jeśli wolisz filtrować centralnie) i zapisz. Od tej pory GitHub podpisuje każde dostarczenie na ten adres Twoim sekretem, a endpoint DueReason weryfikuje ten podpis -- X-Hub-Signature-256, HMAC-SHA256 liczone z dokładnej, surowej treści żądania -- zanim spojrzy na cokolwiek innego w danych. Dostarczenie bez pasującego sekretu, albo takie, które w ogóle nie pochodzi z GitHuba, jest odrzucane, zanim jeszcze odczytane zostaną etykieta czy repozytorium.
Co się dopasowuje, a co jest po cichu ignorowane
Trzy rzeczy muszą się zgodzić, żeby dostarczenie otworzyło wniosek: typ zdarzenia GitHuba musi być issues albo pull_request, jego pole action musi być dokładnie labeled (dodanie etykiety -- usunięcie jej, albo każde inne zdarzenie dotyczące zgłoszenia czy PR-a, nie pasuje), a repozytorium i nazwa etykiety w zdarzeniu muszą odpowiadać temu, co skonfigurowano w endpoincie. Nic z tego nie jest stanem błędu: dostarczenie, które niczego z tego nie spełnia, to po prostu operacja bez efektu, a DueReason i tak odpowiada GitHubowi sukcesem, żeby dostarczenie nie było ponawiane. Jedyny przypadek, który faktycznie kończy się błędem, to dostarczenie z niepoprawnym podpisem albo adres URL bez pasującego endpointu -- te wracają jako prawdziwe błędy HTTP.
Ponowienia też są obsłużone: GitHub wysyła ponownie dostarczenie, które się przeterminowało albo zakończyło błędem, za każdym razem z tym samym identyfikatorem X-GitHub-Delivery. DueReason zapisuje ten identyfikator przy endpoincie, zanim zrobi cokolwiek innego, więc powtórzone dostarczenie już obsłużonego zdarzenia jest rozpoznawane jako to samo zdarzenie i odpowiadane bez otwierania drugiego wniosku.
Mapowanie pól GitHuba na wniosek
Szablon danych to zwykły JSON z placeholderami {{ścieżka.po.kropce}} rozwiązywanymi względem zdarzenia, które otrzymał DueReason: issue.* i pull_request.* dla samego oznaczonego elementu (title, number, html_url, body i tak dalej, zależnie od tego, co faktycznie wywołało zdarzenie), a także repository.*, label.* i sender.* dla pozostałych pól zdarzenia najwyższego poziomu. Pole, które jest *tylko* jednym placeholderem, jak "{{issue.number}}", zachowuje własny typ tego pola -- liczba zostaje liczbą, a nie zamienia się w tekst "42" -- podczas gdy placeholder osadzony w dłuższym tekście zawsze zamienia się w tekst. Ścieżka, której zdarzenie faktycznie nie ma, rozwiązuje się do null zamiast przerywać dostarczenie; to, co naprawdę bramkuje wniosek, to własny schemat payloadu docelowej akcji, dokładnie tak jak przy wniosku złożonym w jakikolwiek inny sposób -- więc szablon, który mapuje wymagane pole na ścieżkę, której zdarzenie nigdy nie niesie, nie przejdzie tej samej walidacji, co ręcznie złożony wniosek z brakującym polem.
Dlaczego to wniosek, a nie powiadomienie
Flow w Zapierze czy n8n uruchamiany etykietą, który wysyła wiadomość na kanał czatu, informuje kogoś, że potrzebna jest decyzja; nie tworzy niczego, co zapisuje, kto zdecydował, w ramach jakiego workflow, ani co dałoby się sprawdzić później. Ponieważ to otwiera prawdziwy wniosek DueReason, w pełni obowiązuje zwykły workflow -- trafienie do właściwej grupy zatwierdzających, wymóg pisemnego uzasadnienia tam, gdzie akcja go wymaga, podpisany grant po decyzji -- a sam wniosek, decyzja i grant trafiają na ten sam rejestr powiązany hashami, co wniosek złożony z konsoli albo z API. Przepis na automatyzację bez kodu pokazuje kierunek odwrotny -- reagowanie na własne zdarzenie approval.approved z DueReason, gdy taki wniosek zostanie zdecydowany -- jeśli chcesz też podłączyć to, co dzieje się *po* zatwierdzeniu.
Czego tu jeszcze nie ma
To domyka trzy planowane źródła przychodzące (GitHub, Linear, Jira); nie ma instalowalnej aplikacji GitHub ani wpisu w Marketplace, który dodawałby to do repozytorium -- każdy endpoint konfiguruje się ręcznie, dla każdej organizacji osobno, w konsoli DueReason, względem webhooka GitHuba, Lineara lub Jiry, który ustawiasz sam, dokładnie tak jak przy każdej innej integracji.
Pytania
- Czy usunięcie etykiety też otwiera wniosek?
- Nie. Dopasowuje się wyłącznie akcja webhooka GitHuba labeled -- dodanie skonfigurowanej etykiety do zgłoszenia lub pull requestu. Usunięcie etykiety, komentarz, zamknięcie czy każde inne zdarzenie dotyczące zgłoszenia lub PR-a jest ignorowane, bez otwarcia wniosku i bez błędu.
- Co się dzieje, gdy GitHub ponawia dostarczenie, bo pierwsza próba się przeterminowała?
- GitHub wysyła ponownie dostarczenie z tym samym identyfikatorem X-GitHub-Delivery, a DueReason zapisuje ten identyfikator przy endpoincie, zanim zrobi cokolwiek innego, więc ponowione dostarczenie jest rozpoznawane jako to już obsłużone, zamiast otwierać drugi wniosek.
- Czy sekret webhooka to ta sama wartość whsec_... co w webhookach wychodzących DueReason?
- Nie, i działają w przeciwnych kierunkach. Sekret webhooków wychodzących (Ustawienia > Webhooki) wydaje DueReason, żebyś mógł zweryfikować dostarczenia, które DueReason wysyła do Ciebie. Ten sekret przychodzący generujesz sam i wklejasz zarówno w DueReason, jak i w ustawieniach webhooka repozytorium na GitHubie, żeby DueReason mógł zweryfikować dostarczenia, które wysyła mu GitHub.
- Czy mogę skonfigurować to dla Lineara albo Jiry zamiast GitHuba?
- Tak, obu. Przy Linearze wybierz źródło Linear i skonfiguruj klucz zespołu oraz docelowy status workflow, a przy Jirze wybierz źródło Jira i skonfiguruj klucz projektu oraz docelowy status -- każde z nich otwiera wniosek tak samo jak dopasowanie etykiety na GitHubie. Endpoint Jiry uwierzytelnia współdzielony nagłówek-sekret (X-DueReason-Jira-Secret) zamiast podpisu HMAC, ponieważ rejestracja webhooka w Jira Cloud nie ma pola na sekret HMAC.
- Czy muszę zainstalować aplikację GitHub albo dodać to do GitHub Marketplace?
- Nie. Każdy endpoint to webhook, który dodajesz w ustawieniach własnego repozytorium (Settings > Webhooks), wskazujący adres wygenerowany przez DueReason dla Twojej organizacji. Nie ma tu aplikacji GitHub do zainstalowania ani wpisu w Marketplace.
- Co się dzieje, gdy mój szablon danych odwołuje się do pola, którego zdarzenie nie ma?
- Szablon zwraca dla tego placeholdera null, zamiast przerywać dostarczenie. Wniosek mimo to się otwiera, ale własny schemat payloadu docelowej akcji waliduje go dokładnie tak jak każdy inny wniosek -- więc wymagane pole zmapowane na ścieżkę, której zdarzenie nigdy nie niesie, nie przejdzie tej samej walidacji, co ręcznie złożony wniosek z brakującym polem.
Otwórz swój pierwszy wniosek z etykiety na GitHubie
Dodaj endpoint przychodzący z GitHuba w Ustawienia > Webhooki przychodzące, wskaż go w webhooku repozytorium i oznacz zgłoszenie etykietą, żeby zobaczyć wniosek.
Załóż kontoŹródła
- Dokumentacja GitHub: Webhook events and payloads -- issues
- Dokumentacja GitHub: Webhook events and payloads -- pull_request
- Dokumentacja GitHub: Validating webhook deliveries
Poradnik wyjaśnia przepisy tak, jak je rozumiemy; nie jest poradą prawną. Sprawdź tekst urzędowy i prawo krajowe, które może dodać obowiązki.