Synchronizacja z GitLab

Ta funkcja została opracowana przez ayaka-notes/ayakaleaf-pro. Jest dostępna od wersji v6.4.0. Nadal znajduje się w fazie beta. Jeśli napotkasz jakiekolwiek problemy, prosimy o opinię.

Synchronizacja z GitLab działa podobnie jak synchronizacja z GitHub: użytkownicy łączą swoje konto GitLab, eksportują projekty do nowych projektów GitLab, importują repozytoria GitLab i synchronizują zmiany w obu kierunkach. Działa z GitLab.com oraz z samodzielnie zarządzanym GitLab w wersji 15.10 lub nowszej (Community Edition i Enterprise Edition).

​

Konfiguracja synchronizacji z GitLab

Przed użyciem synchronizacji z GitLab musisz najpierw włączyć git-bridge.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Utwórz aplikację OAuth w swojej instancji GitLab, w sekcji User settings → Applications (lub Admin area → Applications w przypadku aplikacji dla całej instancji):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: zaznaczone
• Scopes: api

Skopiuj Application ID oraz Secret, a następnie dodaj poniższe ustawienia do plików ze zmiennymi środowiskowymi Overleaf.

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
# (Optional) GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808

Przed skonfigurowaniem adresu URI przekierowania GitLab OAuth upewnij się, że OVERLEAF_SITE_URL jest ustawiony poprawnie.

Tokeny dostępu GitLab wygasają po dwóch godzinach. Overleaf odświeża je za pomocą tokenu odświeżania, który GitLab wydaje razem z nimi, dzięki czemu użytkownicy pozostają połączeni, dopóki nie odłączą konta lub nie unieważnią aplikacji w GitLab.

​

Samodzielnie zarządzany GitLab

Ustaw GITLAB_SYNC_URL na adres internetowy swojej instancji, czyli ten, pod którym otwierasz projekty w przeglądarce. Adres REST API jest z niego wyprowadzany:

Zmienna	Wartość domyślna
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Ustawiaj GITLAB_SYNC_API_URL tylko wtedy, gdy Twoja instancja udostępnia API pod innym adresem, na przykład za bramą API.

• Utwórz aplikację OAuth w instancji ustawionej w GITLAB_SYNC_URL — aplikacja z gitlab.com nie działa w samodzielnie zarządzanej instancji.
• GITLAB_SYNC_URL to wyłącznie adres internetowy. Nie dodawaj /api/v4 ani ścieżki grupy.

Jeśli Twoja instancja używa certyfikatu wystawionego przez prywatny urząd certyfikacji (CA), zamontuj certyfikat CA w kontenerze i wskaż go w NODE_EXTRA_CA_CERTS, np. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitlab-ca.pem.

Połączone konta i projekty należą do instancji, z którą zostały połączone. Przed przełączeniem GITLAB_SYNC_URL na inną instancję poproś użytkowników o odłączenie ich kont GitLab i projektów.

Jeśli znajdujesz się w regionie z ograniczonym dostępem do sieci, może być konieczne skonfigurowanie proxy, aby uzyskać dostęp do GitLab. Ustaw następującą zmienną środowiskową: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Musi to być standardowy serwer proxy przekazujący HTTP/HTTPS i nie może używać 127.0.0.1.

​

Kto może łączyć i synchronizować

Podobnie jak w Overleaf Cloud, tylko właściciel projektu może połączyć projekt z repozytorium GitLab. Po połączeniu każdy współpracownik z uprawnieniami do edycji może go synchronizować.

Działanie	Kto może je wykonać
Eksport projektu do nowego repozytorium GitLab	Właściciel projektu
Import repozytorium GitLab do nowego projektu	Dowolny użytkownik, który staje się właścicielem nowego projektu
Pobieranie, wypychanie i scalanie połączonego projektu	Właściciel i współpracownicy z uprawnieniami do edycji
Odłączenie projektu od repozytorium	Właściciel projektu

• Overleaf komunikuje się z GitLab przy użyciu konta GitLab użytkownika, który synchronizuje, więc każdy synchronizujący współpracownik łączy własne konto GitLab i musi mieć uprawnienia do wypychania zmian do domyślnej gałęzi repozytorium.
• Współpracownicy z dostępem tylko do odczytu nie mogą korzystać z synchronizacji z GitLab w danym projekcie.

​

Jak działa synchronizacja z GitLab

• Uprawnienia: użytkownicy muszą mieć uprawnienia do wypychania zmian do domyślnej gałęzi połączonego projektu. Gdy domyślna gałąź jest chroniona, a użytkownik nie może do niej wypychać zmian, Overleaf prosi go o kontakt z właścicielem projektu, tak jak w przypadku repozytorium, do którego utracił dostęp.
• Scalanie: gdy projekt zmienił się zarówno w Overleaf, jak i w GitLab, Overleaf zatwierdza swoje zmiany w tymczasowej gałęzi o nazwie overleaf-YYYY-MM-DD-HHMMSS i scala ją za pomocą merge requestu, ponieważ GitLab nie udostępnia API do scalania gałęzi bez niego. Po scaleniu Overleaf usuwa tymczasową gałąź i merge request. W GitLab tylko administratorzy i właściciele projektów mogą usuwać merge requesty, więc w przypadku innych użytkowników scalony merge request pozostaje w projekcie.
• Reguły scalania: Overleaf nigdy nie omija reguł scalania projektu. Gdy merge request ma konflikt albo wymaga zatwierdzenia lub pomyślnie zakończonego potoku, pozostaje otwarty, a Overleaf prosi użytkownika o scalenie go w GitLab, a następnie o kontynuowanie synchronizacji.
• Potoki: commity z Overleaf uruchamiają potoki tak jak każdy inny commit. Jeśli Twój projekt uruchamia potoki dla merge requestów i wymaga ich pomyślnego zakończenia, scalenia z Overleaf czekają na nie, jak opisano powyżej.

​

Pytania i odpowiedzi

Czy mogę wymusić wypchnięcie (force push) do domyślnej gałęzi?

Odpowiedź: Prosimy o pozostawienie wyłączonej możliwości wymuszonego wypychania do domyślnej gałęzi. Jest to domyślne ustawienie GitLab: domyślna gałąź nowego projektu jest chroniona i nikt nie może wymusić do niej wypchnięcia. Overleaf potrafi przejąć przepisaną gałąź, ale synchronizacja z GitLab jest zaprojektowana dla domyślnej gałęzi, której historia tylko rośnie.

Czy mogę zmienić nazwę domyślnej gałęzi połączonego projektu?

Odpowiedź: Nie. Overleaf nadal synchronizuje się z gałęzią, z którą projekt został połączony, więc synchronizacje kończą się niepowodzeniem, gdy nazwa tej gałęzi zostanie zmieniona lub gałąź zostanie usunięta. Aby synchronizować z inną gałęzią, odłącz projekt, a następnie zaimportuj repozytorium do nowego projektu, który będzie używał bieżącej domyślnej gałęzi.