Przejdź do treści

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

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.

Zacznij z DueReason

Załóż bezpłatne konto, wypróbuj na żywo albo porozmawiaj z nami o swoim procesie.

Otrzymuj nowości o produkcie