Synchronizace s Gitea

Tuto funkci vyvinul projekt ayaka-notes/ayakaleaf-pro. Je k dispozici ve verzi v6.3.2 jako předběžná verze (early preview) a oficiálně bude vydána ve verzi v6.4.0, takže se její konfigurace a chování ještě mohou změnit. Pokud narazíte na jakýkoli problém, uvítáme vaši zpětnou vazbu.

Synchronizace s Gitea funguje stejně jako synchronizace s GitHubem a synchronizace s GitLabem: uživatelé propojí svůj účet Gitea, exportují projekty do nových repozitářů v Gitea, importují repozitáře z Gitea a synchronizují změny oběma směry. Funguje s Gitea verze 1.23 nebo novější, na gitea.com i na vaší vlastní instanci.

​

Nastavení synchronizace s Gitea

Před použitím synchronizace s Gitea musíte nejprve povolit git-bridge.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Vytvořte OAuth2 aplikaci na své instanci Gitea v části Settings → Applications → Manage OAuth2 applications (nebo Site Administration → Integrations → Applications pro aplikaci pro celou instanci):

• Application name: např. Overleaf; uživatelé jej uvidí při autorizaci aplikace
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: zaškrtnuto

Zkopírujte Client ID a Client Secret a poté přidejte následující nastavení do souborů s proměnnými prostředí Overleafu.

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

Před konfigurací redirect URI v Gitea se ujistěte, že je OVERLEAF_SITE_URL nastaveno správně.

Overleaf si při propojení účtu vyžádá vše, co synchronizace potřebuje, takže uživatelé nikdy nemusí účet propojovat znovu kvůli chybějícímu oprávnění:

Oprávnění	Použití
write:repository	Repozitáře, jejich soubory (včetně CI workflow v .gitea/workflows), větve a pull requesty
write:user	Vytvoření repozitáře uživatele při exportu (Gitea jej vyžaduje u POST /user/repos)
write:organization	Výpis organizací uživatele a vytvoření repozitáře organizace při exportu

Gitea tato oprávnění zobrazí, když uživatel aplikaci autorizuje, a token na ně omezí.

Přístupové tokeny Gitea vyprší po hodině ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf je obnovuje pomocí obnovovacího tokenu, který Gitea vydává spolu s nimi, a to i tehdy, když Gitea obnovovací tokeny po použití spotřebovává (INVALIDATE_REFRESH_TOKENS = true), takže uživatelé zůstávají propojeni, dokud propojení nezruší nebo dokud aplikaci v Gitea neodvolají.

​

Vaše instance Gitea

Nastavte GITEA_SYNC_URL na webovou adresu své instance, tedy její ROOT_URL, přes kterou otevíráte repozitáře v prohlížeči. Adresa REST API je od ní odvozena:

Proměnná	Výchozí hodnota
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Funguje i Gitea provozovaná pod podcestou, např. GITEA_SYNC_URL=https://example.com/gitea. GITEA_SYNC_API_URL nastavujte pouze tehdy, když vaše instance poskytuje API jinde, například za API gateway.

• OAuth2 aplikaci vytvořte na instanci, kterou nastavíte v GITEA_SYNC_URL; aplikace z jiné instance nefunguje.
• GITEA_SYNC_URL je pouze webová adresa. Nepřidávejte /api/v1 ani cestu k uživateli či organizaci.
• Overleaf vytváří commity pomocí souborového API Gitea, které vyžaduje webový editor: ponechte [repository.editor] povolený (výchozí nastavení).

Pokud vaše instance používá certifikát od soukromé certifikační autority, připojte certifikát CA do kontejneru a nastavte na něj NODE_EXTRA_CA_CERTS, např. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem.

Propojené účty a projekty patří k instanci, se kterou byly propojeny. Před přepnutím GITEA_SYNC_URL na jinou instanci požádejte uživatele, aby zrušili propojení svého účtu Gitea a projektů.

Pokud se nacházíte v regionu s omezeným přístupem k síti, možná budete muset pro přístup k Gitea nakonfigurovat proxy. Nastavte následující proměnnou prostředí: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Musí jít o standardní dopřednou HTTP/HTTPS proxy a nesmí používat 127.0.0.1.

​

Kdo může propojovat a synchronizovat

Stejně jako v Overleaf Cloud může projekt s repozitářem Gitea propojit pouze vlastník projektu. Po propojení jej může synchronizovat každý spolupracovník s oprávněním k úpravám.

Akce	Kdo ji může provést
Export projektu do nového repozitáře Gitea	Vlastník projektu
Import repozitáře Gitea do nového projektu	Kterýkoli uživatel, který se stane vlastníkem nového projektu
Pull, push a merge propojeného projektu	Vlastník a spolupracovníci s oprávněním k úpravám
Zrušení propojení projektu s jeho repozitářem	Vlastník projektu

• Overleaf komunikuje s Gitea prostřednictvím účtu Gitea uživatele, který synchronizuje, takže každý spolupracovník, který synchronizuje, si propojí vlastní účet Gitea a musí mít oprávnění pushovat do výchozí větve repozitáře.
• Spolupracovníci s oprávněním pouze ke čtení nemohou pro projekt synchronizaci s Gitea používat.
• Zrušením propojení účtu v Overleafu se zapomene jeho token; Gitea nemá API pro jeho odvolání, takže pokud chcete, odvolejte udělený přístup také v Gitea v části Settings → Applications.

​

Jak funguje synchronizace s Gitea

• Oprávnění: uživatelé musí mít oprávnění pushovat do výchozí větve propojeného repozitáře. Pokud uživateli pravidlo ochrany větve push do ní nepovoluje, Overleaf jej požádá, aby kontaktoval vlastníka projektu, stejně jako u repozitáře, ke kterému ztratil přístup.
• Slučování: pokud se projekt změnil v Overleafu i v Gitea, Overleaf commitne své změny do dočasné větve s názvem overleaf-YYYY-MM-DD-HHMMSS a sloučí ji prostřednictvím pull requestu s výchozím stylem slučování repozitáře, protože Gitea nemá API pro slučování větví bez něj. Po sloučení Overleaf dočasnou větev smaže; sloučený pull request zůstane v repozitáři jako záznam.
• Pravidla slučování: Overleaf nikdy neobchází ochranu větví repozitáře. Pokud má pull request konflikt nebo vyžaduje schválení či úspěšné stavové kontroly, zůstane otevřený a Overleaf požádá uživatele, aby jej sloučil v Gitea a poté pokračoval v synchronizaci.
• CI workflow: Overleaf nezobrazuje soubory začínající tečkou, jako je .gitea/workflows/, a ponechává je v repozitáři beze změny. Commity z Overleafu spouštějí Gitea Actions jako jakékoli jiné commity.

​

Q&A

Mohu do výchozí větve provést force push?

Odpověď: Ponechte prosím force push do výchozí větve zakázaný, např. pomocí pravidla ochrany větve. Overleaf dokáže převzít přepsanou větev, ale synchronizace s Gitea je navržena pro výchozí větev, jejíž historie pouze roste.

Mohu přejmenovat výchozí větev propojeného projektu?

Odpověď: Ne. Overleaf nadále synchronizuje s větví, se kterou byl projekt propojen, takže po přejmenování nebo odstranění této větve synchronizace selžou. Chcete-li synchronizovat s jinou větví, zrušte propojení projektu a poté importujte repozitář do nového projektu, který použije aktuální výchozí větev.

Podporuje synchronizace s Gitea Git LFS?

Odpověď: Ne. Projekty Overleafu nepodporují Git Large File Storage. Soubory sledované pomocí Git LFS se v Overleafu zobrazí jako soubory s LFS ukazateli, nikoli jako jejich obsah. Obrázky a PDF proto commitujte přímo do repozitáře.

Funguje s repozitáři SHA-256?

Odpověď: Zatím ne. Overleaf porovnává soubory podle jejich SHA-1 ID, takže v repozitáři vytvořeném s formátem objektů SHA-256 každý pull přepíše všechny soubory, i ty nezměněné. Nic se neztratí, ale používejte prosím výchozí formát SHA-1.

Funguje s Forgejo?

Odpověď: Synchronizace s Gitea je vyvíjena a testována pouze proti Gitea.