Integrazione Git

Consenti agli utenti di clonare, eseguire pull e push dei propri progetti con Git tramite il git-bridge.

Al momento l’integrazione Git è disponibile in ayaka-notes/overleaf.

Questa funzionalità è stata sviluppata inizialmente da ayaka-notes/ayakaleaf-pro.

1. Abilitare il git-bridge (solo per gli utenti del Toolkit)

   Se usi il Toolkit, abilita il git-bridge impostando quanto segue nel tuo config/overleaf.rc:

   config/overleaf.rc

   GIT_BRIDGE_ENABLED=true
   

   Il Toolkit la ignora a meno che non sia impostata anche SERVER_PRO=true. Non serve altro: il Toolkit imposta autonomamente GIT_BRIDGE_HOST, GIT_BRIDGE_PORT e V1_HISTORY_URL per il container sharelatex, quindi salta i due passaggi Docker Compose qui sotto. Esegui bin/up per ricreare i container.

2. Aggiungere il container git-bridge (solo per gli utenti di Docker-compose)

   Per gli utenti che usano un docker-compose.yml personalizzato, aggiungi la seguente configurazione del container al tuo file compose:

   docker-compose.yml (git-bridge service)

   git-bridge:
       restart: always
       image: ghcr.io/ayaka-notes/overleaf-pro/git-bridge:6.3.2 # tag should match the `sharelatex` container tag
       volumes:
           - ~/git_bridge_data:/data/git-bridge
       container_name: git-bridge
       expose:
           - "8000"
       environment:
           GIT_BRIDGE_API_BASE_URL: "http://sharelatex:3000/api/v0/" 
           GIT_BRIDGE_OAUTH2_SERVER: "http://sharelatex"
           GIT_BRIDGE_POSTBACK_BASE_URL: "http://git-bridge:8000"
           GIT_BRIDGE_ROOT_DIR: "/data/git-bridge"
       user: root
       command: ["/server-pro-start.sh"]
   

   Usa lo stesso tag dell’immagine sharelatex. Il server MCP (v6.3.1 e successive) fa parte dell’immagine sharelatex e viene abilitato insieme all’integrazione Git, quindi non richiede un container aggiuntivo.

3. Aggiornare la configurazione del container sharelatex

   Dovrai anche collegare il container git-bridge nel container sharelatex e definire le seguenti variabili d’ambiente; presta attenzione a V1_HISTORY_URL:

   docker-compose.yml (sharelatex service)

   sharelatex:
       links:
           - git-bridge
       environment:
            GIT_BRIDGE_ENABLED: true
            GIT_BRIDGE_HOST: "git-bridge"
            GIT_BRIDGE_PORT: "8000"
            # We use v1 now, if you used to set V1_HISTORY_URL, please update now
            V1_HISTORY_URL: "http://sharelatex:3100/api"
   
4. Autenticazione

   Per autenticare un client git, gli utenti hanno bisogno di un Personal Access Token. Gli utenti possono gestire i Personal Access Token tramite l’interfaccia dell’applicazione (consulta la documentazione):

   

   Personal Access Token per l'integrazione Git

5. Monitoraggio e considerazioni sulle risorse

   Ti consigliamo di monitorare le risorse dell’host dopo aver abilitato il git-bridge. L’aumento del carico dipenderà da:

   • il numero di utenti che accedono alla funzionalità
   • i tipi di progetti ospitati nella tua istanza (i progetti più grandi richiedono generalmente più risorse)

​

Spostare i progetti su S3 (swap)

L’integrazione Git memorizza su disco un repository git completo per ogni progetto clonato da un utente. Se hai uno spazio su disco limitato, puoi attivare un job di swap che sposterà su AWS S3 i repository meno usati. Se un repository spostato serve di nuovo, viene riportato su disco. Le seguenti variabili d’ambiente controllano il job di swap:

Nome	Descrizione
GIT_BRIDGE_SWAPSTORE_TYPE	Impostala su “s3” per attivare il job di swap.
GIT_BRIDGE_SWAPSTORE_AWS_ACCESS_KEY	La tua access key AWS
GIT_BRIDGE_SWAPSTORE_AWS_SECRET	Il tuo secret AWS
GIT_BRIDGE_SWAPSTORE_S3_BUCKET_NAME	Questo bucket conterrà i repository git compressi in zip
GIT_BRIDGE_SWAPSTORE_AWS_REGION	La regione del bucket
GIT_BRIDGE_SWAPJOB_MIN_PROJECTS	Numero minimo di progetti da mantenere su disco. - Predefinito: 50
GIT_BRIDGE_SWAPJOB_LOW_GIB	Soglia inferiore per lo swap. Il job di swap sposterà i progetti finché l’utilizzo del disco non scende sotto questo valore. - Predefinito: 128 GB
GIT_BRIDGE_SWAPJOB_HIGH_GIB	Soglia superiore per lo swap. Il job di swap inizierà a spostare i progetti quando l’utilizzo del disco raggiunge questo valore. - Predefinito: 256 GB
GIT_BRIDGE_SWAPJOB_INTERVAL_MILLIS	Intervallo di tempo tra un controllo dell’utilizzo del disco e l’esecuzione del job di swap. - Predefinito: 3600000 ms = 1 ora

​

Domande e risposte

Se condivido il mio progetto con qualcun altro, come funziona il modello di permessi del Git Bridge?

Gli utenti con accesso in sola lettura possono solo clonare il progetto; gli utenti con accesso in lettura e scrittura possono clonare ed eseguire il push dei progetti. Nota: gli utenti devono aver effettuato l’accesso per unirsi al progetto.

Come clono un progetto e quale nome utente e password devo usare?

Nell’editor, apri Integrations nella barra laterale sinistra e fai clic su Git integration. Viene mostrato il comando di clonazione, nella forma:

git clone https://<your-overleaf>/git/<project_id>

Quando Git chiede le credenziali, inserisci git come nome utente e un Personal Access Token come password. Genera il token in Account Settings; è valido per un anno. La password del tuo account non funziona.

Le modifiche non vengono sincronizzate automaticamente: usa git pull per ottenere le modifiche fatte nell’editor e git push per inviare le tue. Il percorso /git è servito dal container sharelatex, quindi un reverse proxy posto davanti non richiede regole aggiuntive.

git push non riesce con HTTP 413 o curl 55 Broken pipe

Il push supera il limite di dimensione del caricamento, impostato da MAX_UPLOAD_SIZE (in megabyte, 50 per impostazione predefinita), che vale anche per i push. Aumentalo in config/variables.env, ad esempio MAX_UPLOAD_SIZE=200, quindi esegui bin/up -d. Se usi il TLS proxy o un tuo reverse proxy, aumenta anche il relativo client_max_body_size (50M nel file config/nginx/nginx.conf del Toolkit).

Il git-bridge rifiuta inoltre i file più grandi di 50 MB e i progetti con più di 2.000 file. Questi limiti sono impostati da GIT_BRIDGE_REPOSTORE_MAX_FILE_SIZE (in byte) e GIT_BRIDGE_REPOSTORE_MAX_FILE_NUM in config/variables.env.

Il log del git-bridge mostra Failed to fetch log level

L’avviso è innocuo, e clone, pull e push continuano a funzionare. Nella 6.2.x, il git-bridge chiede una volta al minuto un livello di log al server dei metadati di Google Cloud (metadata.google.internal), cosa che funziona solo su Google Cloud. Altrove la richiesta non riesce, il git-bridge registra l’errore (ad esempio null o uno stato HTTP) e mantiene il livello di GIT_BRIDGE_LOG_LEVEL. Dalla 6.3.0 il controllo è disattivato, e l’aggiornamento aggiorna anche l’immagine del git-bridge, la cui versione segue quella dell’immagine principale.

Mi servono il servizio track-changes o OVERLEAF_IS_SERVER_PRO=true per Git e la cronologia completa del progetto?

Risposta: No. Ayakaleaf Pro non ha un servizio track-changes. La cronologia del progetto è conservata dai servizi project-history e history-v1, che vengono sempre eseguiti all’interno del container sharelatex. Il git-bridge legge la cronologia da history-v1 all’indirizzo V1_HISTORY_URL (http://sharelatex:3100/api), che il Toolkit imposta. Non impostare OVERLEAF_IS_SERVER_PRO: nessuna funzionalità dipende da essa, cambia soltanto le migrazioni del database eseguite all’avvio, passando a quelle di Server Pro.