Synchronizacja z Gitea

Ta funkcja została opracowana przez ayaka-notes/ayakaleaf-pro. Została wprowadzona w wersji v6.3.2 jako wczesna wersja zapoznawcza i zostanie oficjalnie wydana w wersji v6.4.0, więc jej konfiguracja i działanie mogą się jeszcze zmienić. Jeśli napotkasz jakiekolwiek problemy, prosimy o opinię.

Synchronizacja z Gitea działa podobnie jak synchronizacja z GitHub i synchronizacja z GitLab: użytkownicy łączą swoje konto Gitea, eksportują projekty do nowych repozytoriów Gitea, importują repozytoria Gitea i synchronizują zmiany w obu kierunkach. Działa z Gitea w wersji 1.23 lub nowszej, zarówno na gitea.com, jak i we własnej instancji.

​

Konfiguracja synchronizacji z Gitea

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Utwórz aplikację OAuth2 w swojej instancji Gitea, w sekcji Settings → Applications → Manage OAuth2 applications (lub Site Administration → Integrations → Applications w przypadku aplikacji dla całej instancji):

• Application name: np. Overleaf — użytkownicy widzą tę nazwę podczas autoryzacji
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: zaznaczone

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

config/variables.env

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

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

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

Overleaf prosi o wszystkie uprawnienia potrzebne do synchronizacji już w momencie łączenia konta, dzięki czemu użytkownicy nigdy nie muszą łączyć go ponownie z powodu brakującego uprawnienia:

Zakres	Zastosowanie
write:repository	Repozytoria, ich pliki (w tym przepływy CI w .gitea/workflows), gałęzie i pull requesty
write:user	Tworzenie repozytorium użytkownika podczas eksportu (Gitea wymaga go dla POST /user/repos)
write:organization	Wyświetlanie listy organizacji użytkownika i tworzenie repozytorium organizacji podczas eksportu

Gitea wyświetla te zakresy, gdy użytkownik autoryzuje aplikację, i ogranicza do nich token.

Tokeny dostępu Gitea wygasają po godzinie ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf odświeża je za pomocą tokenu odświeżania, który Gitea wydaje razem z nimi, również wtedy, gdy Gitea unieważnia tokeny odświeżania po użyciu (INVALIDATE_REFRESH_TOKENS = true), dzięki czemu użytkownicy pozostają połączeni, dopóki nie odłączą konta lub nie unieważnią aplikacji w Gitea.

​

Twoja instancja Gitea

Ustaw GITEA_SYNC_URL na adres internetowy swojej instancji, czyli jej ROOT_URL — ten, pod którym otwierasz repozytoria w przeglądarce. Adres REST API jest z niego wyprowadzany:

Zmienna	Wartość domyślna
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Gitea udostępniana pod ścieżką podrzędną również działa, np. GITEA_SYNC_URL=https://example.com/gitea. Ustawiaj GITEA_SYNC_API_URL tylko wtedy, gdy Twoja instancja udostępnia API pod innym adresem, na przykład za bramą API.

• Utwórz aplikację OAuth2 w instancji ustawionej w GITEA_SYNC_URL — aplikacja z innej instancji nie działa.
• GITEA_SYNC_URL to wyłącznie adres internetowy. Nie dodawaj /api/v1 ani ścieżki użytkownika lub organizacji.
• Overleaf tworzy commity za pomocą API plików Gitea, które wymaga edytora webowego: pozostaw włączone [repository.editor] (ustawienie domyślne).

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/gitea-ca.pem.

Połączone konta i projekty należą do instancji, z którą zostały połączone. Przed przełączeniem GITEA_SYNC_URL na inną instancję poproś użytkowników o odłączenie ich kont Gitea 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 Gitea. Ustaw następującą zmienną środowiskową: GITEA_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 Gitea. 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 Gitea	Właściciel projektu
Import repozytorium Gitea 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 Gitea przy użyciu konta Gitea użytkownika, który synchronizuje, więc każdy synchronizujący współpracownik łączy własne konto Gitea 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 Gitea w danym projekcie.
• Odłączenie konta w Overleaf usuwa jego token; Gitea nie udostępnia API do jego unieważnienia, więc jeśli chcesz, unieważnij również uprawnienie w Gitea w sekcji Settings → Applications.

​

Jak działa synchronizacja z Gitea

• Uprawnienia: użytkownicy muszą mieć uprawnienia do wypychania zmian do domyślnej gałęzi połączonego repozytorium. Gdy reguła ochrony gałęzi nie pozwala użytkownikowi wypychać do niej 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 Gitea, Overleaf zatwierdza swoje zmiany w tymczasowej gałęzi o nazwie overleaf-YYYY-MM-DD-HHMMSS i scala ją za pomocą pull requestu z domyślnym stylem scalania repozytorium, ponieważ Gitea nie udostępnia API do scalania gałęzi bez niego. Po scaleniu Overleaf usuwa tymczasową gałąź; scalony pull request pozostaje w repozytorium jako zapis.
• Reguły scalania: Overleaf nigdy nie omija ochrony gałęzi repozytorium. Gdy pull request ma konflikt albo wymaga zatwierdzeń lub pomyślnie zakończonych sprawdzeń stanu, pozostaje otwarty, a Overleaf prosi użytkownika o scalenie go w Gitea, a następnie o kontynuowanie synchronizacji.
• Przepływy CI: Overleaf nie wyświetla plików ukrytych (dotfiles), takich jak .gitea/workflows/, i pozostawia je w repozytorium bez zmian. Commity z Overleaf uruchamiają Gitea Actions tak jak każdy inny commit.

​

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, np. za pomocą reguły ochrony gałęzi. Overleaf potrafi przejąć przepisaną gałąź, ale synchronizacja z Gitea 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.

Czy synchronizacja z Gitea obsługuje Git LFS?

Odpowiedź: Nie. Projekty Overleaf nie obsługują Git Large File Storage. Pliki śledzone przez Git LFS pojawiają się w Overleaf jako pliki wskaźników LFS, a nie jako ich zawartość. Zamiast tego zatwierdzaj obrazy i pliki PDF bezpośrednio w repozytorium.

Czy działa z repozytoriami SHA-256?

Odpowiedź: Jeszcze nie. Overleaf porównuje pliki według ich identyfikatorów SHA-1, więc w repozytorium utworzonym z formatem obiektów SHA-256 każde pobranie (pull) przepisuje wszystkie pliki, nawet niezmienione. Nic nie zostaje utracone, ale prosimy o używanie domyślnego formatu SHA-1.

Czy działa z Forgejo?

Odpowiedź: Synchronizacja z Gitea jest tworzona i testowana wyłącznie z Gitea.