Integracje

Orbit pozwala projektowi połączyć się z zewnętrznymi narzędziami, wzdłuż trzech osobnych osi: integracje notify (dziś: Discord; Slack i inne widnieją w katalogu jako "coming soon") wypychają aktywność Orbita na zewnątrz przez webhook, integracje import (dziś: Jira; Linear, Asana, Trello to na razie same wpisy w katalogu) ściągają issues/epiki/subtaski z zewnętrznego systemu na żądanie, a github — jedyna integracja tego rodzaju — łączy pull request z issue w Orbicie poprzez instalację GitHub App. Ta kategoria dokumentuje cały system: katalog na froncie, ustawienia per-projekt zapisywane w bazie danych, opartą na eventach ścieżkę zmieniającą "coś się wydarzyło w Orbit" w "wiadomość dotarła na Discorda", opartą na pull'u ścieżkę zmieniającą "użytkownik kliknął Import" w "issues z Jiry istnieją w Orbicie" oraz ścieżkę opartą na relayu, która łączy pull request z GitHuba z issue w Orbicie.

Przewodniki, w kolejności, w jakiej faktycznie będą potrzebne

1. Dodaj nową integracjęIntegracjeDodaj nową integracjęPrzećwiczony przykład: zamiana Slacka z zablokowanej karty "coming soon" w katalogu w w pełni działającą integrację, dokładnie tak, jak dziś działa Discord… — zamień wpis w katalogu oznaczony jako "coming soon" (lub całkiem nowy) w realnie działającą integrację notify, od początku do końca.
2. Dodaj ustawienia integracjiIntegracjeDodaj ustawienia integracjiprojectintegrations przechowuje obecnie, dla każdej pary projekt+integracja: — nadaj integracji notify własny kształt konfiguracji wykraczający poza "enabled" i URL webhooka (np. nazwa kanału, klucz API, opcja liczbowa).
3. Dodaj nowy typ eventuIntegracjeDodaj nowy typ eventuPrzećwiczony przykład: dodanie IssueCreated — rodzaju aktywności, który jeszcze nie istnieje. Dziś stworzenie issue odpala tylko IssueAssigned, i to tylko… — podepnij zupełnie nowy rodzaj aktywności (na przykładzie IssueCreated), tak żeby zarówno powiadomienia użytkownika, jak i integracje notify mogły na niego reagować.
4. Przegląd połączenia frontend ↔ backendIntegracjePrzegląd połączenia frontend ↔ backendMapa całej funkcji, przydatna do przeczytania przed zagłębieniem się w którykolwiek z pozostałych przewodników. Trzy oddzielne przepływy: czytanie strony u… — pełny kształt request/response dla funkcji integracji notify, przydatny jako mapa przed zagłębieniem się w przewodniki 1–3.
5. Dodaj integrację typu importIntegracjeDodaj integrację typu importPrzećwiczony przykład: zamiana Linear z zablokowanej karty "coming soon" w katalogu w w pełni działającą integrację typu import, dokładnie tak, jak dziś dz… — zamień wpis w katalogu oznaczony jako "coming soon" w realnie działającą integrację import (na przykładzie Lineara, zbudowanym na już kompletnej implementacji Jiry).
6. Integracja z GitHubemIntegracjeIntegracja z GitHubemW przeciwieństwie do integracji typu notify (webhook) i import (pull) opisanych w innych przewodnikach z tej kategorii, GitHub to trzeci rodzaj: instalacja… — jak działa faktyczna, już podłączona integracja typu github: architektura (poprzez relay orbit-api), łączenie projektu, składnia znacznika <!-- orbit-issue:ID --> oraz rozwiązywanie problemów.

Potrzebujesz zabezpieczyć nową zdolność integracji własnym uprawnieniem? Zobacz ../permissions/01-add-a-new-permission.mdRole i uprawnienia (RBAC)Dodaj nowe uprawnienieOgólny, krok-po-kroku wzorzec dodawania dowolnego nowego uprawnienia projects./issues./comments. i sprawienia, żeby poprawnie pojawiło się w Settings → Rol… w kategorii role i uprawnieniaRole i uprawnienia (RBAC)Każdy projekt ma własną kontrolę dostępu opartą na rolach: cztery wbudowane poziomy roli systemowej (Owner, Admin, Member, Viewer) oraz dowolną liczbę proj… — ten przewodnik nie jest tu powtórzony, ponieważ dotyczy dowolnego uprawnienia projects.*/issues.*/comments.*, nie tylko tych związanych z integracjami.

Architektura w jednym akapicie

Frontend ma statyczny katalog (resources/js/types/Integrations.ts) każdej integracji, jaką Orbit mógłby kiedykolwiek wspierać — nazwa, ikona, kategoria, opis, pod-opcje oraz dyskryminator kind: 'notify' | 'import' | 'github' — niezależnie od tego, czy jest już faktycznie podłączona (comingSoon: true/false). Stan per-projekt (czy jest włączona, jej URL webhooka/credentiale, które pod-opcje są aktywne) żyje w jednej tabeli w bazie danych, project_integrations. Dla integracji notify eventy domenowe (App\Events\*), które już istnieją dla powiadomień w aplikacji/mailem — IssueAssigned, IssueUnassigned, IssueUpdated, CommentAdded — są również konsumowane przez drugi listener, NotifyProjectIntegrationsListener, który mapuje każdy event na kategorię pod-opcji (issue-activity / comment-activity) i przekazuje go do odpowiedniego IntegrationNotifier, jaki projekt danego eventu ma włączony dla tej kategorii. Dla integracji import nie ma eventu, na który trzeba by reagować — akcja kontrolera wysyła zakolejkowanego joba, który rozwiązuje IntegrationImporter, mapuje surowy payload zewnętrznego systemu na źródłowo-agnostyczny ExternalIssueDTO i przekazuje każdy DTO do współdzielonego ImportOrchestratorService, który obsługuje deduplikację (external_issue_links), mapowanie pól (integration_field_mappings) oraz hierarchię (Issue::parent_id) w ten sam sposób, niezależnie od tego, który zewnętrzny system wyprodukował dany DTO. Integracja typu github to trzeci, samodzielny kształt: instalacja GitHub App jest proxowana przez publiczny relay orbit-api (zobacz przewodnik 06IntegracjeIntegracja z GitHubemW przeciwieństwie do integracji typu notify (webhook) i import (pull) opisanych w innych przewodnikach z tej kategorii, GitHub to trzeci rodzaj: instalacja…), a nie webhook czy import oparty na pull'u, więc ma własny panel ustawień (WorkspaceSettingsGithubConnectPanel) i własny zaplanowany poller (PollGithubRelayEvents) zamiast korzystać z mechanizmów notify/import. Dodanie integracji, nowego rodzaju eventu albo nowego importera nigdy nie wymaga dotykania wewnętrznych mechanizmów pozostałych osi — zobacz przewodniki, żeby dokładnie zobaczyć, gdzie podłącza się każdy nowy element.