[Intum](https://intum.pl/pomoc.md) / [Integracje](https://intum.pl/pomoc/integracje.md) # [GitHub - automatyczne komentarze pod taskami przy pull requestach](https://intum.pl/pomoc/integracje/github.md) | [API](#api) ## Co robi ta integracja Łączy GitHuba z Intum tak, że kiedy ktoś otworzy albo zmerguje pull requesta na GitHubie, pod powiązanym taskiem w Intum automatycznie pojawia się komentarz. Warunek jest jeden: w opisie PR-a musi być link do tego taska. Autora PR-a (lub osobę, która go zmergowała) staramy się przypisać do właściwego użytkownika Intum po loginie GitHuba zapisanym w profilu - dzięki temu komentarz pojawia się "od tej osoby", a nie anonimowo. ## Jak to skonfigurować Całą konfigurację zrobisz w jednej aplikacji w Intum, bez ruszania kodu. 1. W **Ustawieniach konta** wejdź w **Integracje i dodatki** i zainstaluj **Integracja z GitHub (webhooki PR)**. Po instalacji aplikacja pojawi się na liście aplikacji konta. 2. Otwórz aplikację. Sama wygeneruje losowy sekret i pokaże gotowy adres webhooka, który trzeba wkleić do GitHuba. 3. W repozytorium na GitHubie wejdź w **Settings → Webhooks → Add webhook** i uzupełnij: - **Payload URL** - skopiuj z aplikacji w Intum. - **Content type** - wybierz `application/json`. - **Secret** - wklej sekret wygenerowany przez Intum (zostanie zapisany po obu stronach i służy do weryfikacji każdego przychodzącego zdarzenia). - **Which events would you like to trigger this webhook?** - wybierz opcję "Let me select individual events." i zaznacz **tylko jeden** checkbox: **Pull requests**. Wszystkie pozostałe checkboxy odznacz, włącznie z domyślnie zaznaczonym "Pushes". 4. Zapisz webhook w GitHubie przyciskiem **Add webhook**. 5. Wróć do aplikacji w Intum i kliknij **Utwórz konektor**. Od tego momentu integracja jest aktywna. Możesz podłączyć kilka repozytoriów - w każdym z nich konfigurujesz osobny webhook, ale wszystkie wskazują na ten sam adres w Intum i używają tego samego sekretu. ## Jak z tego korzystać W opisie pull requesta wklej pełny link do taska w Intum, np.: ``` https://twoja-firma.intum.com/organize/tasks/123 ``` Możesz wkleić go w dowolnym miejscu opisu, razem z innym tekstem - integracja wyszukuje pierwsze pasujące wystąpienie. Co się stanie dalej: - Po otwarciu PR-a pod taskiem pojawi się komentarz typu "Nowy pull request , stworzony przez: ". - Po zmergowaniu PR-a dopisze się drugi komentarz: "Pull request , zmergowany przez: ". - Zwykłe zamknięcie PR-a bez merga, push do brancha, review itd. nie tworzą żadnych komentarzy. ## Mapowanie autora PR-a na użytkownika Intum Żeby komentarz został podpisany właściwą osobą, ta osoba musi mieć uzupełniony swój login GitHuba w profilu w Intum (w sekcji identyfikatorów zewnętrznych). Bez tego komentarz pojawi się z domyślnego konta technicznego "GitHub" - sama treść (kto otworzył lub zmergował) będzie poprawna, ale komentarz nie zostanie powiązany z konkretnym kontem Intum. ## Bezpieczeństwo Każde zdarzenie przychodzące z GitHuba weryfikujemy podpisem cyfrowym wyliczonym z sekretu. Jeśli sekret w GitHubie i w Intum się rozjadą (np. ktoś wygeneruje nowy po jednej ze stron), webhooki przestaną być przyjmowane do czasu wyrównania. W aplikacji w Intum możesz w każdej chwili wygenerować nowy sekret - po jego wygenerowaniu trzeba ten sam sekret wpisać też w ustawieniach webhooka w GitHubie. ## Co zrobić, jeśli nie działa - **Otwieram PR i nic się nie dzieje pod taskiem** - upewnij się, że w opisie PR-a jest link do konkretnego taska w formacie `https://twoja-firma.intum.com/organize/tasks/`. Bez linku integracja nie wie, do którego taska dopisać komentarz. - **GitHub pokazuje błąd 401 przy próbie dostarczenia webhooka** (zakładka Recent Deliveries w ustawieniach webhooka) - sekret w GitHubie i w Intum nie są identyczne. Wygeneruj nowy w aplikacji Intum i przeklej go do GitHuba. - **Komentarz pojawia się, ale podpisany "GitHub" zamiast osobą** - autor PR-a nie ma wpisanego swojego loginu GitHuba w profilu w Intum. - **Webhook nie dociera w ogóle** - sprawdź w GitHubie zakładkę Recent Deliveries: jest tam pełna historia prób z odpowiedzią serwera. Pomaga to szybko zlokalizować, czy problem jest po stronie GitHuba (np. zła ścieżka), czy Intum (np. nieaktywny konektor). --- ## API ### Ogólne API # Intum API Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy. ## Host Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta) ## Autoryzacja Wszystkie requesty API wymagają `api_token`: - header: `Authorization: Bearer TOKEN` Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API** ## Konektor - Typ: `service/github_webhook` - Endpoint przyjmujący webhooki: `POST https://.intum.com/connect/connector//receive` - Autoryzacja: HMAC-SHA256 z `secret_token` konektora w nagłówku `X-Hub-Signature-256` (format `sha256=`, porównanie w czasie stałym). ## Pola konektora | Pole | Opis | |------|------| | `secret_token` | Wartość identyczna z polem "Secret" przy konfiguracji webhooka w GitHubie. | | `fields.url_regexp` | Regexp dopasowywany do `pull_request.body`. Domyślny: `https://[^/]+\.intum\.com/organize/tasks/(\d+)`. Pierwsza grupa to ID taska. | | `fields.title_start` | Opcjonalna tablica prefiksów tytułu PR-a. Jeśli `url_regexp` nie znajdzie taska, a tytuł zaczyna się od któregoś z tych prefiksów - integracja zapisuje aktywność `github_opened` / `github_closed` zamiast komentarza. | ## Obsługiwane zdarzenia Akceptowane jest wyłącznie zdarzenie `pull_request` (`X-GitHub-Event: pull_request`) z `action`: - `opened` - PR utworzony - `closed` z `merged: true` - PR zmergowany Wszystkie inne wartości `action` (m.in. `synchronize`, `closed` z `merged: false`, `edited`, `reopened`) są ignorowane i zwracają `200 OK` bez efektu. ## Mapowanie autora Login GitHuba (`pull_request.user.login` przy `opened`, `pull_request.merged_by.login` przy zmergowanym `closed`) jest mapowany na użytkownika Intum po polu `external_id` w `Account::UserSetting`. Brak dopasowania = komentarz przypisywany do technicznego użytkownika o ID `-1`. ## Tworzenie konektora przez API ```json POST /connect/connectors.json Content-Type: application/json { "connector": { "kind": "service/github_webhook", "code": "github_webhook", "name": "GitHub Webhook (PR)", "active": true, "secret_token": "<48-znakowy hex>", "fields": { "url_regexp": "https://twoja-firma\\.intum\\.com/organize/tasks/(\\d+)" } } } ``` ## Przykładowy payload z GitHuba Minimalna struktura odbierana z GitHuba (skrócona): ```json { "action": "opened", "pull_request": { "html_url": "https://github.com/firma/repo/pull/42", "title": "Fix login bug", "body": "Naprawia logowanie. Task: https://twoja-firma.intum.com/organize/tasks/123", "merged": false, "user": { "login": "janKowalski" }, "merged_by": null } } ``` Dla zmergowanego PR-a `action: "closed"`, `merged: true`, `merged_by: { "login": "..." }`.