Przejdź do treści

Otwórz wniosek DueReason, gdy zgłoszenie w Linearze zmieni status

Przenieś zgłoszenie w Linearze do skonfigurowanego statusu workflow, a DueReason automatycznie otworzy podpisany wniosek o zatwierdzenie -- bez pollingu.

Aktualizacja · 7 min czytania

W skrócie

  • Endpoint przychodzący z Lineara wiąże jeden zespół i jeden status workflow z jedną akcją DueReason: przejście zgłoszenia w tym zespole do tego statusu 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 Lineara (Settings > API > Webhooks).
  • Szablon danych mapuje pola zdarzenia z Lineara na własny payload akcji za pomocą placeholderów w stylu `{{data.title}}`, więc otwarty wniosek niesie realne dane, a nie tylko odnośnik z powrotem do Lineara.
  • Dopasowuje się wyłącznie zdarzenie Issue z akcją `update`, w którym status faktycznie się zmienił przy tym dostarczeniu, a nowy zespół i nazwa statusu odpowiadają konfiguracji endpointu -- edycja tytułu, komentarz albo zgłoszenie po prostu leżące w docelowym statusie są po cichu ignorowane.
  • GitHub to drugie źródło na tym samym schemacie: skonfigurowane repozytorium i etykieta, zamiast zespołu i docelowego statusu, otwiera wniosek, gdy ta etykieta zostanie dodana. Dostępne jest też konsolowe źródło `custom` do podłączenia webhooka dowolnego innego systemu.

Przenoszenie zgłoszenia do kolumny Done, Ready for release albo Needs budget to w wielu zespołach inżynieryjnych już dziś sposób na oznaczenie "to jest skończone, ktoś musi to zatwierdzić" -- sam status niesie moment decyzji, zanim ktokolwiek zapisze ją gdziekolwiek indziej. Endpoint przychodzący z Lineara zamienia to przejście statusu w prawdziwy wniosek o zatwierdzenie w DueReason w chwili, gdy się wydarza -- z podpisanym grantem i wpisem w rejestrze za decyzją, zamiast wiadomości na Slacku, o której ktoś musi pamiętać.

Co się właściwie dzieje

Każdy endpoint przychodzący wiąże jeden zespół w Linearze (po kluczu zespołu, np. ENG) i jedną nazwę statusu workflow (np. Done) z jedną akcją DueReason. W chwili, gdy zgłoszenie w tym zespole przejdzie do tego statusu, DueReason otwiera wniosek względem wybranej akcji, wypełniony danymi ze zdarzenia: tytuł w stylu Linear: ENG issue moved to "Done", powód wskazujący zgłoszenie z odnośnikiem z powrotem do Lineara, 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 ze źródłem Linear pyta o cztery rzeczy: Klucz zespołu (klucz zespołu w Linearze, np. ENG), Docelowy status (dokładna nazwa statusu workflow, która po przejściu zgłoszenia otwiera wniosek, np. Done), 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 Lineara, na przykład { "title": "{{data.title}}", "url": "{{url}}" }. Wklejasz tu też Sekret podpisujący webhooka Linear: wartość, którą *sam* generujesz, a nie taką, którą wydaje DueReason -- dokładnie tę samą wartość wkleisz za chwilę do Lineara, 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/linear-inbound/{endpointId}. Nic się nie uruchomi, dopóki ten adres nie zostanie zarejestrowany po stronie Lineara.

Potem wskaż go w Linearze

W ustawieniach Lineara, Settings > API > Webhooks, dodaj webhook z tym adresem, wybierz zdarzenie Issues i wklej ten sam sekret, który przed chwilą wpisałeś w DueReason, jako sekret podpisujący webhooka. Od tej pory Linear podpisuje każde dostarczenie na ten adres Twoim sekretem, a endpoint DueReason weryfikuje ten podpis -- nagłówek Linear-Signature, HMAC-SHA256 liczone z dokładnej, surowej treści żądania, zakodowane szesnastkowo bez żadnego prefiksu (inaczej niż GitHubowe sha256=...) -- zanim spojrzy na cokolwiek innego w danych. Dostarczenie bez pasującego sekretu, albo takie, które w ogóle nie pochodzi z Lineara, jest odrzucane, zanim jeszcze odczytane zostaną zespół czy status.

Co się dopasowuje, a co jest po cichu ignorowane

Kilka rzeczy musi się zgodzić, żeby dostarczenie otworzyło wniosek: typ zdarzenia z Lineara musi być Issue, jego pole action musi być dokładnie update, a -- inaczej niż samo sprawdzenie bieżącego statusu zgłoszenia -- pole updatedFrom tego dostarczenia musi faktycznie nieść stateId, czyli status workflow naprawdę się zmienił przy *tym* dostarczeniu, a nie jakieś inne, niezwiązane pole (np. edycja tytułu) na zgłoszeniu, które już wcześniej leżało w docelowym statusie. Do tego klucz zespołu i nowa nazwa statusu 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 Linearowi 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: powtórzone dostarczenie niesie za każdym razem ten sam nagłówek Linear-Delivery (jego brak trasa odrzuca od razu), a 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 Lineara na wniosek

Szablon danych to zwykły JSON z placeholderami {{ścieżka.po.kropce}} rozwiązywanymi względem zdarzenia, które otrzymał DueReason: data.* dla samego zgłoszenia (id, title i inne pola, które niesie payload Lineara), a także team.* i state.* dla nowego zespołu i statusu zgłoszenia, actor.* dla osoby, która dokonała zmiany, oraz pole najwyższego poziomu url z odnośnikiem z powrotem do zgłoszenia w Linearze. Pole, które jest *tylko* jednym placeholderem, zachowuje własny typ tego pola zamiast zamieniać się w tekst -- dokładnie jak w źródle GitHub; ścieżka, której zdarzenie faktycznie nie ma, rozwiązuje się do null zamiast przerywać dostarczenie, a to, co naprawdę bramkuje wniosek, to własny schemat payloadu docelowej akcji -- 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

Wiadomość na Slacku wywołana zmianą statusu w Linearze 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. Analogiczna konfiguracja po stronie GitHuba jest opisana w przewodniku o zgłoszeniach/PR z GitHuba: ten sam schemat, oznaczone etykietą zgłoszenie lub PR zamiast zmiany statusu.

Czego tu jeszcze nie ma

Konsolowy podgląd "wyślij przykładowe zdarzenie", dostępny dla źródeł GitHub i custom, nie jest jeszcze dostępny dla Lineara -- nie ma testowego przebiegu na fikcyjnych danych przed podłączeniem prawdziwego webhooka Lineara; pierwsze prawdziwe dostarczenie to też pierwsza rzecz, którą można sprawdzić, w dzienniku dostarczeń endpointu. Jira też nie jest dziś dostępna, i nie ma instalowalnej integracji z Linearem z jego własnego marketplace'u -- każdy endpoint konfiguruje się ręcznie, dla każdej organizacji osobno, w konsoli DueReason, względem webhooka Lineara, który ustawiasz sam, dokładnie tak jak przy każdej innej integracji.

Pytania

Czy edycja tytułu zgłoszenia albo dodanie komentarza też otwiera wniosek?
Nie. Dopasowuje się wyłącznie zdarzenie Issue update, którego updatedFrom niesie stateId -- czyli status workflow faktycznie się zmienił przy tym dostarczeniu -- a nowy klucz zespołu i nazwa statusu muszą następnie odpowiadać konfiguracji endpointu. Każda inna edycja pola, komentarz, albo zgłoszenie, które już leży w docelowym statusie i zostało tknięte z niezwiązanego powodu, jest ignorowane, bez otwarcia wniosku i bez błędu.
Co się dzieje, gdy Linear ponawia dostarczenie, bo pierwsza próba się przeterminowała?
Linear wysyła ponownie dostarczenie z tym samym identyfikatorem Linear-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ść co sekret webhooków 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 we własnych ustawieniach Lineara (Settings > API > Webhooks), żeby DueReason mógł zweryfikować dostarczenia, które wysyła mu Linear.
Czy mogę skonfigurować to dla GitHuba albo Jiry zamiast Lineara?
Dla GitHuba tak: przy dodawaniu endpointu wybierz źródło GitHub i skonfiguruj repozytorium oraz etykietę zamiast zespołu i docelowego statusu -- dodanie tej etykiety do zgłoszenia lub pull requestu otwiera wniosek. Jira to planowany kolejny krok, który miałby wykorzystać ten sam schemat, a nie coś, co można skonfigurować już teraz; ogólne źródło custom już dziś obsłuży dowolny inny system.
Czy mogę podejrzeć, co zmiana statusu w Linearze by otworzyła, zanim podłączę prawdziwy webhook?
Jeszcze nie. Konsolowy test "wyślij przykładowe zdarzenie" istnieje dziś dla źródeł GitHub i custom, nie dla Lineara, więc pierwsze prawdziwe dostarczenie do Twojego endpointu to też pierwsze, które możesz sprawdzić -- w dzienniku dostarczeń endpointu.
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 ze zmiany statusu w Linearze

Dodaj endpoint przychodzący z Lineara w Ustawienia > Webhooki przychodzące, wskaż go we własnych ustawieniach webhooków Lineara i przenieś zgłoszenie do skonfigurowanego statusu, ż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