Sincronizzazione con GitHub

Consenti agli utenti di sincronizzare i propri progetti con repository GitHub o GitHub Enterprise.

Questa funzionalità è sviluppata da ayaka-notes/ayakaleaf-pro e modificata da yu-i-i/overleaf-cep. È disponibile dalla v6.2.0 in poi ed è ancora in fase beta. Se riscontri problemi, abbiamo bisogno del tuo feedback.

​

Configurare la sincronizzazione con GitHub

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Visita le impostazioni sviluppatore per creare la tua applicazione OAuth di GitHub e copia il CLIENT_ID e il SECRET.

Note: quando crei la OAuth App, inserisci ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback in Authorization callback URL. Ayakaleaf Pro costruisce lo stesso indirizzo a partire da OVERLEAF_SITE_URL, quindi non c’è nulla da impostare in config/variables.env.

Quindi aggiungi le seguenti impostazioni ai file delle variabili d’ambiente di Overleaf.

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

Prima di configurare l’URL di callback OAuth di GitHub, assicurati che OVERLEAF_SITE_URL sia impostato correttamente.

Se ti trovi in una regione con accesso alla rete limitato, potrebbe essere necessario configurare un proxy per accedere a GitHub. Imposta la seguente variabile d’ambiente: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Assicurati che l’uso di un proxy sia conforme alle leggi e ai regolamenti locali.

GITHUB_SYNC_PROXY_URL deve essere un forward proxy HTTP/HTTPS standard (ad esempio la porta HTTP di Clash). I mirror di download di GitHub come gh-proxy.org non sono supportati.

Non usare 127.0.0.1 come host del proxy. Se il proxy è in esecuzione sul server host, usa l’indirizzo IP LAN del server (ad esempio 192.168.1.xx) e assicurati che il proxy sia configurato per accettare connessioni dai dispositivi della rete locale.

​

GitHub Enterprise

Il supporto a GitHub Enterprise è disponibile dalla v6.3.1 in poi. Le versioni precedenti si connettono solo a github.com e le variabili seguenti non hanno alcun effetto.

Per impostazione predefinita, la sincronizzazione con GitHub si connette a github.com. Per usare GitHub Enterprise Server (self-hosted) o GitHub Enterprise Cloud con residenza dei dati (GHE.com), imposta GITHUB_SYNC_URL sull’indirizzo web della tua istanza, quello con cui apri i repository nel browser.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Gli endpoint delle API REST e GraphQL vengono ricavati da GITHUB_SYNC_URL nello stesso modo in cui lo fa la GitHub CLI:

GITHUB_SYNC_URL	API REST	API GraphQL
https://github.com (predefinito)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (qualsiasi altro)	https://HOST/api/v3	https://HOST/api/graphql

Imposta gli endpoint delle API solo quando la tua istanza li espone altrove, ad esempio dietro un API gateway:

Variabile	Predefinito
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Ricavato da GITHUB_SYNC_URL, vedi la tabella sopra
GITHUB_SYNC_GRAPHQL_URL	Ricavato da GITHUB_SYNC_API_URL se impostato (/api/v3 diventa /api/graphql, altrimenti viene aggiunto /graphql), in caso contrario da GITHUB_SYNC_URL

• Crea l’applicazione OAuth sulla tua istanza enterprise (Settings → Developer settings → OAuth Apps): un’applicazione creata su github.com non funziona lì. L’URL di callback è lo stesso: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL è solo l’indirizzo web. Non impostarlo su un indirizzo API come https://api.github.com o https://HOST/api/v3 e non aggiungere il percorso di un’organizzazione.
• Tutti e tre gli indirizzi devono puntare alla stessa istanza GitHub.

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

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

​

Chi può collegare e sincronizzare

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

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

​

Q&A

Come collego un progetto a GitHub e lo sincronizzo?

Risposta: Nell’editor, apri Integrations e fai clic su GitHub. Se il tuo account GitHub non è ancora collegato, fai prima clic su Link to your GitHub account. In Export Project to GitHub, inserisci un nome per il repository, scegli Private in Repository visibility e fai clic su Create a GitHub repository.

Dopodiché, la stessa scheda apre Sync with GitHub, che elenca i nuovi commit su GitHub. Fai clic su Sync per eseguire il commit delle modifiche fatte in Overleaf sul branch predefinito e portare le modifiche di GitHub nel progetto. La sincronizzazione avviene in entrambe le direzioni, ma viene eseguita solo quando qualcuno fa clic su Sync; non esiste una sincronizzazione pianificata. Quando sono cambiati entrambi i lati, Overleaf esegue il merge tramite un branch temporaneo chiamato overleaf-YYYY-MM-DD-HHMMSS. Se quel merge presenta un conflitto, esegui tu stesso il merge del branch su GitHub, quindi fai clic su I have manually merged. Continue.

Posso eseguire un force push sul branch predefinito?

Risposta: Non lo consigliamo. Overleaf rileva il force push, avvisa e adotta il branch riscritto, unendo le modifiche apportate in Overleaf dall’ultima sincronizzazione. Per evitare sorprese, proteggi il branch predefinito dai force push nelle impostazioni del repository.

Posso rinominare il branch predefinito di un progetto collegato?

Risposta: Ti preghiamo di non farlo. Overleaf continua a sincronizzarsi con il branch a cui il progetto è stato collegato. 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 GitHub mostra «Something wrong with GitHub request»

Risposta: Questo messaggio indica che il server non è riuscito a raggiungere GitHub, ad esempio a causa di un problema di rete, DNS, TLS o proxy. Esegui bin/logs web per vedere l’errore completo. Se il server ha bisogno di un proxy per raggiungere GitHub, imposta GITHUB_SYNC_PROXY_URL.

Devo disattivare «Expire user access tokens» nella GitHub OAuth App?

Risposta: Sì. La sincronizzazione con GitHub non rinnova i token scaduti. Con i token a scadenza abilitati, gli utenti devono collegare di nuovo GitHub ogni volta che il loro token scade.

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 GitHub; se per farlo serve un proxy, imposta GITHUB_SYNC_PROXY_URL. GitHub non contatta mai la tua istanza: un progetto viene sincronizzato solo quando un utente lo sincronizza nell’editor.

Il collegamento del mio account GitHub non riesce o mi riporta indietro senza collegarlo

Risposta: Verifica quanto segue, in quest’ordine:

• Apri Overleaf esattamente all’indirizzo impostato in OVERLEAF_SITE_URL. GitHub ti rimanda a ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback e il tuo accesso esiste solo sull’indirizzo da cui sei partito, quindi un altro host, IP o porta finisce sulla pagina di accesso o su «Restricted, sorry you don’t have permission to load this page».
• L’Authorization callback URL della OAuth App deve essere ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, con lo stesso schema, host e porta.
• Una pagina di errore con Failed to obtain access token from Git server significa che GitHub non ha restituito un token: controlla GITHUB_SYNC_CLIENT_ID e GITHUB_SYNC_CLIENT_SECRET, e che il server possa raggiungere GitHub. Esegui bin/logs web per vedere l’errore completo.

Dopo aver modificato config/variables.env, esegui bin/up per ricreare i container.

L'importazione di un repository non riesce con «EmptyZipFileError: empty_zip_file» o «unzip failed»

Risposta: Overleaf importa l’archivio zip dell’ultimo commit sul branch predefinito del repository, e questo errore significa che l’archivio non contiene alcun file che Overleaf possa importare. Controlla il branch predefinito su GitHub:

• Contiene i file del progetto, non solo file che Overleaf salta durante l’importazione: dotfile come .gitignore e .gitmodules (.latexmkrc viene mantenuto) e file di compilazione come *.aux, *.log, *.bbl, *.synctex.gz, *.doc e *.docx.
• I file non si trovano solo all’interno di submodule Git. L’archivio di GitHub lascia i submodule come cartelle vuote.
• I file che ti aspetti si trovano sul branch predefinito, non su un altro branch. L’importazione usa sempre il branch predefinito.

L'importazione di un repository non riesce con «connect ECONNREFUSED» verso «sharelatex:3054»

Risposta: V1_HISTORY_URL è impostata su http://sharelatex:3054, un valore indicato dalle versioni precedenti di questa documentazione. La porta 3054 è quella del servizio project-history, che è in ascolto solo all’interno del container, mentre V1_HISTORY_URL deve puntare a history-v1. Overleaf salva ogni file binario (immagini, PDF) del repository importato in history-v1, quindi l’importazione non riesce; anche il caricamento di un file di questo tipo nell’editor non riesce allo stesso modo. Nel tuo docker-compose.yml, imposta V1_HISTORY_URL: "http://sharelatex:3100/api" sul servizio sharelatex (vedi Integrazione Git) e ricrea il container. Il Toolkit imposta già questo valore; verifica che docker-compose.override.yml non lo sovrascriva.