Sincronizzazione con Gitea

Questa funzionalità è sviluppata da ayaka-notes/ayakaleaf-pro. È stata introdotta nella v6.3.2 come anteprima e verrà rilasciata ufficialmente nella v6.4.0, quindi la sua configurazione e il suo comportamento potrebbero ancora cambiare. Se riscontri problemi, abbiamo bisogno del tuo feedback.

La sincronizzazione con Gitea funziona come la sincronizzazione con GitHub e la sincronizzazione con GitLab: gli utenti collegano il proprio account Gitea, esportano progetti in nuovi repository Gitea, importano repository Gitea e sincronizzano le modifiche in entrambe le direzioni. Funziona con Gitea 1.23 o successivo, su gitea.com o sulla tua istanza.

​

Configurare la sincronizzazione con Gitea

Prima di usare la sincronizzazione con Gitea devi abilitare git-bridge.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crea un’applicazione OAuth2 sulla tua istanza Gitea, in Settings → Applications → Manage OAuth2 applications (oppure Site Administration → Integrations → Applications per un’applicazione valida per tutta l’istanza):

• Application name: ad es. Overleaf, gli utenti la vedono quando la autorizzano
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: selezionato

Copia il Client ID e il Client Secret, quindi aggiungi le seguenti impostazioni ai file delle variabili d’ambiente di 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

Prima di configurare il redirect URI di Gitea, assicurati che OVERLEAF_SITE_URL sia impostato correttamente.

Overleaf richiede tutto ciò di cui una sincronizzazione ha bisogno nel momento in cui l’utente collega l’account, così gli utenti non devono mai ricollegarlo per un permesso mancante:

Scope	Usato per
write:repository	Repository, i loro file (inclusi i workflow CI in .gitea/workflows), branch e pull request
write:user	Creare un repository dell’utente durante l’esportazione (Gitea lo richiede su POST /user/repos)
write:organization	Elencare le organizzazioni dell’utente e creare un repository di una di esse durante l’esportazione

Gitea mostra questi scope quando l’utente autorizza l’applicazione e limita il token a essi.

I token di accesso di Gitea scadono dopo un’ora ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf li rinnova con il refresh token che Gitea rilascia insieme a essi, anche quando Gitea consuma i refresh token a ogni utilizzo (INVALIDATE_REFRESH_TOKENS = true), così gli utenti restano collegati finché non scollegano o revocano l’applicazione in Gitea.

​

La tua istanza Gitea

Imposta GITEA_SYNC_URL sull’indirizzo web della tua istanza, il suo ROOT_URL, quello con cui apri i repository nel browser. L’API REST viene ricavata da esso:

Variabile	Predefinito
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Funziona anche Gitea servito sotto un sottopercorso, ad es. GITEA_SYNC_URL=https://example.com/gitea. Imposta GITEA_SYNC_API_URL solo quando la tua istanza espone l’API altrove, ad esempio dietro un API gateway.

• Crea l’applicazione OAuth2 sull’istanza impostata in GITEA_SYNC_URL: un’applicazione di un’altra istanza non funziona.
• GITEA_SYNC_URL è solo l’indirizzo web. Non aggiungere /api/v1 né il percorso di un utente o di un’organizzazione.
• Overleaf esegue i commit con l’API dei file di Gitea, che richiede l’editor web: mantieni abilitato [repository.editor] (l’impostazione predefinita).

Se la tua istanza usa un certificato emesso da una CA privata, monta il certificato della CA nel container e fai puntare NODE_EXTRA_CA_CERTS a esso, ad esempio NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem.

Gli account e i progetti collegati appartengono all’istanza con cui sono stati collegati. Prima di cambiare GITEA_SYNC_URL verso un’altra istanza, chiedi agli utenti di scollegare il proprio account Gitea e i propri progetti.

Se ti trovi in una regione con accesso alla rete limitato, potrebbe essere necessario configurare un proxy per accedere a Gitea. Imposta la seguente variabile d’ambiente: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Deve essere un forward proxy HTTP/HTTPS standard e non deve usare 127.0.0.1.

​

Chi può collegare e sincronizzare

Come su Overleaf Cloud, solo il proprietario del progetto può collegare un progetto a un repository Gitea. Una volta collegato, ogni collaboratore con accesso in modifica può sincronizzarlo.

Azione	Chi può farlo
Esportare un progetto in un nuovo repository Gitea	Il proprietario del progetto
Importare un repository Gitea in un nuovo progetto	Qualsiasi utente, che diventa proprietario del nuovo progetto
Eseguire pull, push e merge di un progetto collegato	Il proprietario e i collaboratori con accesso in modifica
Scollegare un progetto dal suo repository	Il proprietario del progetto

• Overleaf comunica con Gitea usando l’account Gitea dell’utente che esegue la sincronizzazione, quindi ogni collaboratore che sincronizza collega il proprio account Gitea e deve avere il permesso di eseguire push sul branch predefinito del repository.
• I collaboratori con accesso in sola lettura non possono usare la sincronizzazione con Gitea per il progetto.
• Scollegando l’account in Overleaf, il suo token viene dimenticato; Gitea non offre un’API per revocarlo, quindi, se vuoi, revoca l’autorizzazione anche in Gitea, in Settings → Applications.

​

Come funziona la sincronizzazione con Gitea

• Permessi: gli utenti devono avere il permesso di eseguire push sul branch predefinito del repository collegato. Quando una regola di protezione del branch non consente all’utente di eseguire push su di esso, Overleaf gli chiede di contattare il proprietario del progetto, come avviene per un repository a cui ha perso l’accesso.
• Merge: quando un progetto è stato modificato sia in Overleaf sia in Gitea, Overleaf esegue il commit delle proprie modifiche su un branch temporaneo chiamato overleaf-YYYY-MM-DD-HHMMSS e lo unisce tramite una pull request con lo stile di merge predefinito del repository, perché Gitea non offre un’API per unire branch senza di essa. Dopo il merge, Overleaf elimina il branch temporaneo; la pull request unita rimane nel repository come traccia.
• Regole di merge: Overleaf non aggira mai la protezione dei branch del repository. Quando la pull request presenta un conflitto, oppure richiede approvazioni o controlli di stato superati, rimane aperta e Overleaf chiede all’utente di eseguire il merge in Gitea e poi di continuare la sincronizzazione.
• Workflow CI: Overleaf non mostra i dotfile come .gitea/workflows/ e li lascia invariati nel repository. I commit provenienti da Overleaf avviano le Gitea Actions come qualsiasi altro commit.

​

Q&A

Posso eseguire un force push sul branch predefinito?

Risposta: Ti preghiamo di mantenere disabilitati i force push sul branch predefinito, ad esempio con una regola di protezione del branch. Overleaf può adottare un branch riscritto, ma la sincronizzazione con Gitea è pensata per un branch predefinito la cui cronologia cresce soltanto.

Posso rinominare il branch predefinito di un progetto collegato?

Risposta: No. Overleaf continua a sincronizzarsi con il branch a cui il progetto è stato collegato, quindi le sincronizzazioni falliscono quando quel branch viene rinominato o rimosso. Per sincronizzarti con un altro branch, scollega il progetto e poi importa il repository in un nuovo progetto, che userà il branch predefinito corrente.

La sincronizzazione con Gitea supporta Git LFS?

Risposta: No. I progetti Overleaf non supportano Git Large File Storage. I file tracciati da Git LFS compaiono in Overleaf come file puntatore LFS e non con il loro contenuto. Esegui invece il commit di immagini e PDF direttamente nel repository.

Funziona con i repository SHA-256?

Risposta: Non ancora. Overleaf confronta i file tramite i loro ID SHA-1, quindi in un repository creato con il formato oggetti SHA-256 ogni pull riscrive tutti i file, anche quelli non modificati. Non si perde nulla, ma ti consigliamo di usare il formato SHA-1 predefinito.

Funziona con Forgejo?

Risposta: La sincronizzazione con Gitea è sviluppata e testata solo con Gitea.