Przejdź do głównej zawartości

Konektory

Konektor to pojedyncze połączenie z jednym systemem kontroli wersji: jednym serwerem GitLab, jedną organizacją GitHub, jedną instancją Bitbucket. Każdy konektor należy do konkretnej Wtyczki, czyli wdrożenia Enterprise Plugin, które faktycznie skanuje repozytoria.

To od konektorów zaczyna się każde wdrożenie Q247, bo bez nich platforma nie ma skąd wziąć commitów, a więc nie ma z czego wyliczyć Kalorii, Przyrostów ani Linii.

Zasada działania​

Wtyczka łączy się z API systemu kontroli wersji, pobiera listę dostępnych repozytoriów i klonuje je lokalnie. Analiza kodu i historii odbywa się w całości po stronie wtyczki. Do Q247 wysyłany jest tylko wynik.

Przebieg od zapisania konektora do danych na dashboardzie ma cztery etapy, a każdy z nich zajmuje czas:

  1. Odkrycie repozytoriów. Wtyczka odpytuje API i zgłasza znalezione repozytoria do Q247. Zajmuje to od 5 do 10 minut.
  2. Przypisanie do projektu. Krok ręczny, bez niego skanowanie nie startuje.
  3. Pierwsze skanowanie. Analiza całej historii repozytorium, od kilkunastu minut w górę, zależnie od rozmiaru.
  4. Aktywacja osób. Krok ręczny, opisany w Uruchomieniu integracji. Bez niego dashboardy pozostają puste.

Zakres przetwarzanych danych​

Kod źródłowy i pełna historia repozytorium są klonowane i analizowane lokalnie, po stronie wtyczki. Nie opuszczają infrastruktury, w której wtyczka działa: w standardowej instalacji jest to infrastruktura Klienta (Private Plugin), a w wariancie Cloud Plugin infrastruktura Q247. Token dostępu również zostaje po stronie wtyczki, z jednym wyjątkiem: w konektorze Generic GIT poświadczenia są częścią adresu repozytorium, więc trafiają do Q247 razem z nim.

Do Q247 trafia wyłącznie wynik analizy: adres repozytorium, dane commitera, wyliczony wektor wysiłku i wynik kaloryczny, wersja modelu oraz metadane repozytorium, czyli nazwa, adres, grupa i status.

Techniczną specyfikację, wraz z listą przechowywanych pól, zawiera Bezpieczeństwo Enterprise Plugin.

Wymagania wstępne​

Konto serwisowe i token​

Uwierzytelnianie odbywa się osobistym tokenem dostępu wygenerowanym na koncie, które ma dostęp do wszystkich repozytoriów przeznaczonych do analizy. To najczęstsza przyczyna niekompletnych wyników: konektor działa, ale odkrywa tylko część repozytoriów, bo konto serwisowe nie należy do wszystkich grup.

Token potrzebuje wyłącznie uprawnień odczytu. W GitLabie odpowiadają im zakresy read_user, read_api i read_repository; w pozostałych systemach ich odpowiedniki.

Token z uprawnieniem zapisu jest niepotrzebnym ryzykiem

Q247 nigdy nie zapisuje niczego do repozytorium. Token z szerszym zakresem niż odczyt nie da żadnej dodatkowej funkcji, a zwiększa skutki jego ewentualnego wycieku.

Poświadczenia ze zmiennych środowiskowych​

Poświadczeń nie trzeba wpisywać do formularza wprost. Zamiast wartości można podać nazwę zmiennej środowiskowej z przedrostkiem $$, a wtyczka odczyta ją dopiero w momencie łączenia się z systemem.

Działa to dla obu pól, nazwy użytkownika i tokenu, niezależnie od siebie. Można więc podać login jawnie, a token ze zmiennej, albo oba ze zmiennych.

PoleWartość w formularzuZmienna na hoście wtyczki
Nazwa użytkownika$$GITLAB_USERGITLAB_USER=q247-service
Osobisty token dostępu (PAT)$$GITLAB_TOKENGITLAB_TOKEN=glpat-xxxxxxxx

Przedrostek to dokładnie dwa znaki dolara, a dalej sama nazwa zmiennej, bez nawiasów i bez spacji. Zapis $GITLAB_TOKEN albo ${GITLAB_TOKEN} nie zostanie rozpoznany i trafi do systemu jako dosłowny ciąg znaków.

W bazie Q247 zapisuje się wtedy wyłącznie nazwa zmiennej, bez samej wartości. Poświadczenie pozostaje na serwerze Klienta i nie przechodzi przez formularz w przeglądarce ani przez backend Q247. Rotacja tokenu sprowadza się wtedy do podmiany zmiennej na hoście i restartu wtyczki, bez wchodzenia do panelu.

Zmienna musi istnieć na hoście wtyczki

Chodzi o maszynę, na której działa wtyczka. Przy Cloud Plugin jest to środowisko po stronie Q247, więc ustawienie zmiennej wymaga udziału zespołu wdrożeniowego; przy wtyczce działającej u Klienta zmienną ustawia jego zespół infrastruktury.

Nieustawiona zmienna nie daje błędu walidacji przy zapisie. Poświadczenie rozwiązuje się do wartości pustej i objawia się dopiero jako nieudane uwierzytelnienie przy pierwszej próbie połączenia, czyli status Błąd na konektorze.

Mechanizm działa w każdym konektorze, który ma pola nazwy użytkownika i tokenu, a więc we wszystkich poza Generic GIT, gdzie poświadczenia wchodzą w adres URL repozytorium. Obsługują go też integracje Jiry i Confluence, wraz z osobnym tokenem Tempo.

Dostęp sieciowy​

Wtyczka musi dosięgnąć API systemu kontroli wersji oraz backendu Q247. Oba połączenia są wychodzące. Przy repozytoriach dodawanych ręcznie w Generic GIT dostęp musi być publiczny albo otwarty dla adresu IP, z którego działa dana wtyczka.

Dodawanie konektora​

W Konfiguracji, w sekcji Wtyczki, przy liście "Konektory" wybranego wdrożenia, przycisk "+" pokazuje listę dostępnych typów.

Wybór typu konektora

Sześć z siedmiu typów ma identyczny formularz. Wyjątkiem jest Generic GIT, który nie łączy się przez API.

Przykładowy formularz konektora (GitLab)

PoleCo robiPrzykład
Nazwa konektorawłasna nazwa do rozpoznania na liścieGitLab firmowy
Wtyczkawdrożenie, które ma obsługiwać ten konektorCloud (Europe)
Adres URL API konektoraadres API systemu kontroli wersjihttps://gitlab.firma.pl/api/v4
Nazwa użytkownikalogin konta, na którym wygenerowano tokenq247-service
Osobisty token dostępu (PAT)poświadczenie konta serwisowegoglpat-xxxxxxxx albo $$GITLAB_TOKEN
ID organizacjiidentyfikator organizacji, tylko dla części typówfirma

Adres API buduje się inaczej dla każdego systemu, a to najczęstsze miejsce pomyłki:

SystemAdres URL API konektora
GitLabhttps://{host}:{port}/api/v4, na przykład https://gitlab.firma.pl/api/v4
GitHubadres API instancji, dla github.com wartość domyślna
Azure DevOpshttps://dev.azure.com
Bitbucket, Gitea, Gerritadres API danej instancji

Pole ID organizacji nie występuje we wszystkich typach: dla Azure DevOps jest wymagane, dla GitHub opcjonalne, a w pozostałych typach nie ma go wcale.

Przycisk zapisu zamyka formularz i uruchamia odkrywanie repozytoriów.

Weryfikacja i diagnostyka​

Kolumna Status na liście konektorów przyjmuje jedną z sześciu wartości:

StatusZnaczenie
Nowykonektor zapisany, wtyczka jeszcze go nie podjęła
Oczekującytrwa pierwsze połączenie z systemem kontroli wersji
Gotowypołączenie nawiązane, repozytoria jeszcze nieprzetworzone
Operacyjnykonektor działa i dostarcza dane
Błądostatnia próba połączenia zakończyła się niepowodzeniem
Zarchiwizowanykonektor wyłączony z użycia, dane historyczne zostają

Status Oczekujący utrzymujący się dłużej niż kilkanaście minut oznacza problem z połączeniem albo z tokenem.

Gdy repozytoria nie pojawiają się w Źródłach, sprawdź kolejno:

  1. Czy minęło 5 do 10 minut i czy odświeżyłeś stronę. Lista nie aktualizuje się sama.
  2. Czy adres API jest poprawny, wraz z sufiksem właściwym dla danego systemu. Adres samej instancji, bez sufiksu API, daje status Błąd.
  3. Czy token nie wygasł i czy ma zakresy odczytu.
  4. Czy konto serwisowe należy do wszystkich grup, których repozytoria mają być analizowane. Objawem jest niekompletna, a nie pusta lista.
  5. Logi wtyczki (q247-plugin.log), które pokazują odpowiedzi API i błędy wysyłki.

Gdy repozytoria są widoczne, ale dashboardy pozostają puste, przyczyna niemal zawsze leży w dwóch krokach opisanych w Uruchomieniu integracji: braku przypisania do projektu albo braku aktywacji osób.

Siedem typów konektorów​

Zobacz też​