Sincronizzazione con GitHub

Consenti agli utenti di sincronizzare i loro progetti con repository GitHub o GitHub Enterprise in un deployment Kubernetes.

La sincronizzazione con GitHub viene eseguita nel servizio web (il modulo github-sync) di ogni pod di Ayakaleaf Pro. Richiede l’integrazione Git. Crea l’applicazione OAuth e leggi cosa fa ciascuna impostazione in Sincronizzazione con GitHub; questa pagina la riporta su Kubernetes.

Servizio	web (modulo github-sync), in ogni pod di Ayakaleaf Pro; letto all’avvio di web
Pod → GitHub	https://api.github.com (REST e GraphQL), oppure l’API di GITHUB_SYNC_URL, ogni volta che un utente collega, importa, esporta o sincronizza
Browser → GitHub	https://github.com/login/oauth/authorize per collegare un account, poi il ritorno a ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback
GitHub → Overleaf	nessuno: nessun webhook, l’istanza non deve essere raggiungibile da GitHub
Dati memorizzati	i token di accesso GitHub dell’utente, cifrati, in MongoDB
Job periodici	nessuno: la sincronizzazione avviene quando un utente fa clic

​

Configurazione

1. ConfigMap

   30-config.yaml (additions)

     GITHUB_SYNC_ENABLED: "true"
     GITHUB_SYNC_CLIENT_ID: <client ID>
     # GitHub Enterprise: its web address
     # GITHUB_SYNC_URL: https://github.example.com
     # optional: send the module's requests to GitHub through an HTTP proxy
     # GITHUB_SYNC_PROXY_URL: http://proxy.example.com:3128
   

   GIT_BRIDGE_ENABLED: "true" e lo StatefulSet di git-bridge descritto in Integrazione Git devono essere presenti: senza di essi le impostazioni dell’account e l’editor nascondono la sincronizzazione con GitHub.

2. Secret

   kubectl -n overleaf patch secret overleaf-secrets --type merge -p '{"stringData":{
     "GITHUB_SYNC_CLIENT_SECRET":"<client secret>",
     "GITHUB_TOKEN_CIPHER_PASSWORD":"'"$(openssl rand -hex 32)"'"}}'
   

   GITHUB_TOKEN_CIPHER_PASSWORD cifra i token di accesso GitHub degli utenti in MongoDB. Tutte le repliche devono usare lo stesso valore, e modificarlo in seguito obbliga ogni utente a collegare di nuovo GitHub.

3. CA privata (facoltativo)

   Se il tuo GitHub usa un certificato emesso dalla tua CA, aggiungi la CA al Secret overleaf-certs montato in /var/lib/overleaf/certs (vedi Certificati e altri file) e imposta NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem nella ConfigMap.

4. Applica, riavvia e verifica

   kubectl apply -f 30-config.yaml
   kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
   for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
     kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" https://api.github.com
   done
   

   Qualsiasi codice di stato HTTP significa che GitHub è raggiungibile da quel pod; 000 significa che non lo è.

​

Più repliche

Nulla di aggiuntivo oltre al valore condiviso di GITHUB_TOKEN_CIPHER_PASSWORD. Una sincronizzazione acquisisce un lock in Redis, condiviso con le altre sincronizzazioni Git, quindi due repliche non sincronizzano mai lo stesso progetto contemporaneamente.

​

Testato su Kubernetes

Contro un mock di github.com e delle sue API REST e GraphQL (considerato attendibile tramite NODE_EXTRA_CA_CERTS da overleaf-certs), su Kubernetes 1.37 con una replica e l’integrazione Git attiva, i nostri test end-to-end per la sincronizzazione con GitHub vengono superati (31 casi): collegamento e scollegamento dell’account, token revocati, esportazione di un progetto in un nuovo repository privato o di un’organizzazione, importazione di un repository (anche oltre il limite di upload), pull e push, merge, conflitti e merge manuali, branch eliminati e sottoposti a force push, file binari, rinomine ed eliminazioni, perdita dell’accesso in push, e cosa possono fare proprietari, editor e lettori.