Sincronizzazione con GitLab

Consenti agli utenti di sincronizzare i propri progetti con repository su GitLab.com o su un GitLab self-managed.

Questa funzionalità è sviluppata da ayaka-notes/ayakaleaf-pro. È stata introdotta nella v6.3.1 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 GitLab funziona come la sincronizzazione con GitHub: gli utenti collegano il proprio account GitLab, esportano progetti in nuovi progetti GitLab, importano repository GitLab e sincronizzano le modifiche in entrambe le direzioni. Funziona con GitLab.com e con GitLab self-managed 15.10 o successivo (Community ed Enterprise Edition).

​

Configurare la sincronizzazione con GitLab

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crea un’applicazione OAuth sulla tua istanza GitLab, in User settings → Applications (oppure Admin area → Applications per un’applicazione valida per tutta l’istanza):

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

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

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

I token di accesso di GitLab scadono dopo due ore. Overleaf li rinnova con il refresh token che GitLab rilascia insieme a essi, così gli utenti restano collegati finché non scollegano o revocano l’applicazione in GitLab.

​

GitLab self-managed

Imposta GITLAB_SYNC_URL sull’indirizzo web della tua istanza, quello con cui apri i progetti nel browser. L’API REST viene ricavata da esso:

Variabile	Predefinito
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Imposta GITLAB_SYNC_API_URL solo quando la tua istanza espone l’API altrove, ad esempio dietro un API gateway.

• Crea l’applicazione OAuth sull’istanza impostata in GITLAB_SYNC_URL: un’applicazione creata su gitlab.com non funziona su un’istanza self-managed.
• GITLAB_SYNC_URL è solo l’indirizzo web. Non aggiungere /api/v4 né il percorso di un gruppo.

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

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

Se ti trovi in una regione con accesso alla rete limitato, potrebbe essere necessario configurare un proxy per accedere a GitLab. Imposta la seguente variabile d’ambiente: GITLAB_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 GitLab. Una volta collegato, ogni collaboratore con accesso in modifica può sincronizzarlo.

Azione	Chi può farlo
Esportare un progetto in un nuovo repository GitLab	Il proprietario del progetto
Importare un repository GitLab 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 GitLab usando l’account GitLab dell’utente che esegue la sincronizzazione, quindi ogni collaboratore che sincronizza collega il proprio account GitLab 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 GitLab per il progetto.

​

Come funziona la sincronizzazione con GitLab

• Permessi: gli utenti devono avere il permesso di eseguire push sul branch predefinito del progetto collegato. Quando il branch predefinito è protetto e l’utente non può 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 GitLab, Overleaf esegue il commit delle proprie modifiche su un branch temporaneo chiamato overleaf-YYYY-MM-DD-HHMMSS e lo unisce tramite una merge request, perché GitLab non offre un’API per unire branch senza di essa. Dopo il merge, Overleaf elimina il branch temporaneo e la merge request. In GitLab solo gli amministratori e i proprietari del progetto possono eliminare le merge request, quindi per gli altri utenti la merge request unita rimane nel progetto.
• Regole di merge: Overleaf non aggira mai le regole di merge del progetto. Quando la merge request presenta un conflitto, oppure richiede un’approvazione o una pipeline superata, rimane aperta e Overleaf chiede all’utente di eseguire il merge in GitLab e poi di continuare la sincronizzazione.
• Pipeline: i commit provenienti da Overleaf avviano le pipeline come qualsiasi altro commit. Se il tuo progetto esegue pipeline per le merge request e ne richiede il superamento, i merge da Overleaf le attendono, come descritto sopra.

​

Q&A

Posso eseguire un force push sul branch predefinito?

Risposta: Ti preghiamo di mantenere disabilitati i force push sul branch predefinito. È l’impostazione predefinita di GitLab: il branch predefinito di un nuovo progetto è protetto e nessuno può eseguire force push su di esso. Overleaf può adottare un branch riscritto, ma la sincronizzazione con GitLab è 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 GitLab 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. Prima di GitLab 17.9, l’importazione di un repository porta con sé il loro contenuto, che la prima sincronizzazione sostituisce con i file puntatore. Esegui invece il commit di immagini e PDF direttamente nel repository.

La mia istanza deve essere raggiungibile da Internet?

Risposta: No. Il collegamento di un account passa dal browser dell’utente, quindi l’indirizzo di callback OAuth deve solo aprirsi nel browser dell’utente. Il server deve soltanto raggiungere GitLab; se per farlo serve un proxy, imposta GITLAB_SYNC_PROXY_URL. GitLab non contatta mai la tua istanza: un progetto viene sincronizzato solo quando un utente lo sincronizza nell’editor.