GitLab

Co robi

Integracja z GitLabem łączy Speedwave z twoją instancją GitLaba, dzięki czemu może czytać repozytoria, obsługiwać merge requesty, uruchamiać i sprawdzać pipeline’y oraz zarządzać zgłoszeniami, gałęziami i wydaniami. Współpracuje i z GitLab.com, i z instancją stawianą u siebie. Speedwave korzysta z niej przy takich zadaniach jak przegląd kodu na merge requeście, dochodzenie, czemu pipeline się wysypał, albo zakładanie zgłoszenia wprost z rozmowy.

Z czego się składa

GitLab to wbudowany worker: Speedwave włącza go oddzielnie dla każdego projektu z poziomu aplikacji Desktop i uruchamia w osobnym kontenerze. Logujesz się za pomocą Personal Access Tokena GitLaba i podajesz adres instancji, dzięki czemu ta sama integracja trafia i na GitLab.com, i na twój własny serwer. Token oraz adres to jedyne poświadczenia, które ten worker u siebie trzyma.

Jak to działa

Speedwave zapisuje adres i token w ~/.speedwave/tokens/<project>/gitlab/ i podłącza je do kontenera workera GitLaba tylko do odczytu. Poświadczenia i docelowy serwer są przypisane do projektu i przemieszczają się razem z nim. W artykule Jak obsługiwane są poświadczenia opisujemy, jak to podłączenie pozostaje odseparowane od pozostałych workerów.

Kiedy coś się nie powiedzie, worker tłumaczy najczęstsze błędy GitLaba na czytelne komunikaty: 401 to nieprawidłowy albo wygasły token, 403 to zbyt małe uprawnienia, 404 mówi, że nie udało się znaleźć danego elementu, 5xx oznacza błąd po stronie serwera GitLaba, a błąd sieci wskazuje, że worker nie mógł połączyć się z ustawionym adresem.

Co potrafi

Worker daje dostęp do 46 narzędzi. Te, które coś kasują lub zmieniają nieodwracalnie, przed uruchomieniem proszą o potwierdzenie.

Narzędzie	Co robi
listProjectIds, getProjectFull	Wypisuje dostępne projekty, a potem pobiera pełne dane wybranego z nich.
searchCode	Szuka w kodzie we wszystkich projektach, do których masz dostęp, albo w obrębie jednego.
getTree, getFile	Przegląda drzewo plików repozytorium i odczytuje zawartość pliku.
getBlame	Zwraca git blame w rozbiciu na poszczególne wiersze. To jeden z tych obszarów, w których GitLab oferuje więcej niż GitHub.
listBranches, getBranch, compareBranches	Wypisuje gałęzie, pokazuje jedną z nich albo porównuje dwie gałęzie lub dwa commity.
createBranch	Tworzy gałąź z podanego refa.
deleteBranch (nieodwracalne)	Kasuje gałąź. Na gałęzi chronionej się nie powiedzie.
listCommits, listBranchCommits, getCommitDiff	Wypisuje commity z filtrami, wypisuje commity z gałęzi albo pobiera diff pojedynczego commita.
searchCommits	Przeszukuje treść commitów. Filtruje po stronie klienta, bo GitLab nie ma osobnego API do przeszukiwania commitów.
listMrIds, getMrFull, getMrChanges	Wypisuje identyfikatory merge requestów, pobiera pełne dane MR-a albo jego diff.
createMergeRequest, updateMergeRequest	Zakłada merge request albo edytuje istniejący.
approveMergeRequest (nieodwracalne)	Zatwierdza merge request.
mergeMergeRequest (nieodwracalne)	Scala merge request, z możliwością zgniecenia commitów w jeden (squash), usunięcia gałęzi źródłowej i włączenia auto-merge.
listMrCommits, listMrPipelines	Wypisuje commity albo pipeline’y powiązane z merge requestem.
listMrNotes, createMrNote	Wypisuje komentarze do merge requesta albo dodaje nowy.
listMrDiscussions, createMrDiscussion	Wypisuje wątki dyskusji na merge requeście albo zakłada nowy.
listPipelineIds, getPipelineFull	Wypisuje identyfikatory pipeline’ów, a potem pobiera pełne dane wybranego.
getJobLog	Zwraca log zadania wprost w odpowiedzi: domyślnie ostatnie 100 wierszy, albo cały log, gdy podasz 0.
retryPipeline	Ponawia nieudany pipeline.
triggerPipeline (nieodwracalne)	Uruchamia nowy pipeline na wskazanym refie, z opcjonalnymi zmiennymi.
listArtifacts, downloadArtifact	Wypisuje artefakty zadań w pipeline albo pobiera jeden z nich. downloadArtifact zleca workerowi samodzielne pobranie zawartości (na razie loga zadania, a nie archiwum artefaktu) i zwraca ją jako nazwę pliku wraz z rozmiarem.
deleteArtifacts (nieodwracalne)	Kasuje artefakty zadania.
listIssues, getIssue	Wypisuje zgłoszenia w projekcie albo pobiera jedno z nich.
createIssue, updateIssue, closeIssue	Zakłada, edytuje albo zamyka zgłoszenie.
listLabels, createLabel	Wypisuje etykiety projektu albo tworzy nową.
createTag	Tworzy tag Gita.
deleteTag (nieodwracalne)	Kasuje tag Gita.
createRelease	Przygotowuje wydanie na podstawie istniejącego taga. Najpierw utwórz tag za pomocą createTag.

Skonfiguruj

1. W aplikacji Desktop otwórz projekt, w którym chcesz mieć GitLaba, przejdź do jego integracji i wybierz GitLab.

2. Wpisz adres GitLaba: https://gitlab.com dla GitLab.com albo adres swojego serwera, jeśli instancję stawiasz u siebie, na przykład https://gitlab.example.com. Zostaw to pole puste, a worker przyjmie domyślnie https://gitlab.com.

   Worker ustala host w takiej kolejności: najpierw plik z zapisanym adresem, potem zmienna środowiskowa GITLAB_URL, a na końcu domyślny https://gitlab.com. Jeśli pipeline’y trafiają na niewłaściwą instancję, sprawdź, które z tych źródeł ustawiło adres.

3. Wklej swój Personal Access Token (zaczyna się od glpat-). Utwórz go na stronie Access Tokens w swoim profilu GitLaba: nadaj mu nazwę i datę wygaśnięcia, zaznacz uprawnienia (scopes) i skopiuj token, bo GitLab pokaże ci go tylko raz.

4. Zapisz. Speedwave zapamiętuje poświadczenia i włącza integrację. Kiedy uruchamiasz ją pierwszy raz, Speedwave buduje obraz workera GitLaba, dlatego ten pierwszy start trwa dłużej od kolejnych.

Service integrations my my-project

servicestatusveron

githubrunningconfigured

gitlabrunningconfigured

slackconfigure →—

Jeśli później znów otworzysz formularz z poświadczeniami i zostawisz pole tokena puste, Speedwave zachowa ten zapisany wcześniej. Nowy wpisuj tylko wtedy, gdy chcesz podmienić stary.

Uprawnienia tokena

Utwórz token z uprawnieniami (scopes), których integracja potrzebuje: przy konfiguracji zalecamy api, read_repository oraz write_repository. Speedwave nie weryfikuje uprawnień w momencie zapisu tokena, więc braki wyjdą na jaw dopiero później, jako 403 z GitLaba. Nazwy uprawnień bywają różne w różnych wersjach GitLaba, dlatego przed utworzeniem tokena zajrzyj do dokumentacji swojej instancji.

Granice bezpieczeństwa

Worker GitLaba nie trzyma niczego poza własnymi poświadczeniami, podłączonymi do jego kontenera tylko do odczytu. Sam hub nie przechowuje żadnych tokenów, a jedynie kieruje wywołania do odpowiedniego workera. Zakres działania integracji wyznaczają uprawnienia Personal Access Tokena, więc token tylko do odczytu nie scali merge requesta ani nie wypchnie zmian, a deleteBranch i tak uszanuje ochronę gałęzi ustawioną w samym GitLabie.