# 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](/pl/docs/features/code-review/) 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](/pl/docs/security/credentials/) 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.

<DesktopFrame screen="integrations" />

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.](/pl/docs/under-the-hood/tool-gateway/) 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.