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.