GitHub-synkronisering

Låt användare synkronisera sina projekt med repositorier på GitHub eller GitHub Enterprise.

Den här funktionen är utvecklad av ayaka-notes/ayakaleaf-pro och modifierad av yu-i-i/overleaf-cep. Den introducerades i v6.2.0 och finns i senare versioner. Den är fortfarande i betastatus. Vi behöver din återkoppling om du stöter på problem.

​

Konfigurera GitHub-synkronisering

Du måste aktivera git-bridge innan du kan använda GitHub-synkronisering.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Gå till utvecklarinställningarna för att skapa din GitHub OAuth-applikation och kopiera ditt CLIENT_ID och SECRET.

Obs! När du skapar OAuth-appen anger du ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback i Authorization callback URL. Ayakaleaf Pro bygger samma adress utifrån OVERLEAF_SITE_URL, så det finns inget att ange för den i config/variables.env.

Lägg sedan till följande inställningar i dina filer med miljövariabler för 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

Kontrollera att OVERLEAF_SITE_URL är korrekt angiven innan du konfigurerar callback-URL:en för GitHub OAuth.

Om du befinner dig i en region med begränsad nätverksåtkomst kan du behöva konfigurera en proxy för att nå GitHub. Ange följande miljövariabel: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Se till att din användning av en proxy följer lokala lagar och föreskrifter.

GITHUB_SYNC_PROXY_URL måste vara en vanlig HTTP/HTTPS-framåtproxy (till exempel HTTP-porten i Clash). GitHub-nedladdningsspeglar som gh-proxy.org stöds inte.

Använd inte 127.0.0.1 som proxyvärd. Om proxyn körs på värdservern använder du serverns LAN-IP-adress (till exempel 192.168.1.xx) och ser till att proxyn är konfigurerad att ta emot anslutningar från enheter i det lokala nätverket.

​

GitHub Enterprise

Stöd för GitHub Enterprise introducerades i v6.3.1 och finns i senare versioner. Tidigare versioner ansluter bara till github.com, och variablerna nedan har ingen effekt.

Som standard ansluter GitHub-synkronisering till github.com. För att använda GitHub Enterprise Server (egen drift) eller GitHub Enterprise Cloud med datalagringsplats (GHE.com) anger du GITHUB_SYNC_URL till webbadressen för din instans, den du öppnar repositorier med i webbläsaren.

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

Ändpunkterna för REST- och GraphQL-API:erna härleds från GITHUB_SYNC_URL på samma sätt som GitHub CLI gör:

GITHUB_SYNC_URL	REST-API	GraphQL-API
https://github.com (standard)	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 (alla andra)	https://HOST/api/v3	https://HOST/api/graphql

Ange bara API-ändpunkterna när din instans tillhandahåller dem någon annanstans, till exempel bakom en API-gateway:

Variabel	Standard
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Härleds från GITHUB_SYNC_URL, se tabellen ovan
GITHUB_SYNC_GRAPHQL_URL	Härleds från GITHUB_SYNC_API_URL när den är angiven (/api/v3 blir /api/graphql, annars läggs /graphql till), i annat fall från GITHUB_SYNC_URL

• Skapa OAuth-applikationen på din enterprise-instans (Settings → Developer settings → OAuth Apps), en applikation från github.com fungerar inte där. Callback-URL:en är densamma: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL är endast webbadressen. Ange den inte till en API-adress som https://api.github.com eller https://HOST/api/v3, och lägg inte till en organisationssökväg.
• Alla tre adresserna måste peka på samma GitHub-instans.

Om din instans använder ett certifikat från en privat CA monterar du CA-certifikatet i containern och låter NODE_EXTRA_CA_CERTS peka på det, t.ex. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Länkade konton och projekt hör till den instans de länkades med. Be användarna att avlänka sitt GitHub-konto och sina projekt innan du byter GITHUB_SYNC_URL till en annan instans.

​

Vem kan länka och synkronisera

Precis som på Overleaf Cloud kan endast projektägaren länka ett projekt till ett GitHub-repositorium. När det väl är länkat kan alla medarbetare med redigeringsbehörighet synkronisera det.

Åtgärd	Vem kan utföra den
Exportera ett projekt till ett nytt GitHub-repositorium	Projektägaren
Importera ett GitHub-repositorium till ett nytt projekt	Alla användare, som då blir ägare till det nya projektet
Hämta, pusha och slå samman ett länkat projekt	Ägaren och medarbetare med redigeringsbehörighet
Avlänka ett projekt från dess repositorium	Projektägaren

• Overleaf kommunicerar med GitHub via GitHub-kontot för den användare som synkroniserar, så varje medarbetare som synkroniserar länkar sitt eget GitHub-konto och måste ha behörighet att pusha till repositoriets standardgren.
• Medarbetare med endast läsbehörighet kan inte använda GitHub-synkronisering för projektet.

​

Q&A

Hur länkar jag ett projekt till GitHub och synkroniserar det?

Svar: Öppna Integrations i redigeraren och klicka på GitHub. Om ditt GitHub-konto inte är länkat än klickar du först på Link to your GitHub account. I Export Project to GitHub anger du ett namn på repositoriet, väljer Private under Repository visibility och klickar på Create a GitHub repository.

Därefter öppnar samma kort Sync with GitHub, som listar de nya commitarna på GitHub. Klicka på Sync för att committa dina Overleaf-ändringar till standardgrenen och hämta in GitHub-ändringarna i projektet. Synkroniseringen går åt båda hållen men körs bara när någon klickar på Sync; det finns ingen schemalagd synkronisering. När båda sidor har ändrats slår Overleaf samman via en tillfällig gren med namnet overleaf-YYYY-MM-DD-HHMMSS. Om den sammanslagningen ger en konflikt slår du själv samman grenen på GitHub och klickar sedan på I have manually merged. Continue.

Kan jag force-pusha till standardgrenen?

Svar: Vi rekommenderar det inte. Overleaf upptäcker en force push, varnar för den och tar över den omskrivna grenen genom att slå samman de ändringar som gjorts i Overleaf sedan den senaste synkroniseringen. För att undvika överraskningar bör du skydda standardgrenen mot force pushes i repositoriets inställningar.

Kan jag byta namn på standardgrenen i ett länkat projekt?

Svar: Gör inte det. Overleaf fortsätter att synkronisera med den gren som projektet länkades till. För att synkronisera med en annan gren avlänkar du projektet och importerar sedan repositoriet till ett nytt projekt, som då använder den aktuella standardgrenen.

GitHub-synkroniseringen visar ”Something wrong with GitHub request”

Svar: Meddelandet innebär att servern inte kunde nå GitHub, till exempel på grund av ett nätverks-, DNS-, TLS- eller proxyproblem. Kör bin/logs web för att se hela felet. Om servern behöver en proxy för att nå GitHub anger du GITHUB_SYNC_PROXY_URL.

Ska jag inaktivera ”Expire user access tokens” i GitHub OAuth-appen?

Svar: Ja. GitHub-synkroniseringen förnyar inte utgångna tokens. Med tokens som löper ut aktiverat måste användarna ansluta GitHub igen varje gång deras token går ut.

Måste min instans vara nåbar från internet?

Svar: Nej. Länkningen av ett konto går via användarens webbläsare, så OAuth-callback-adressen behöver bara kunna öppnas i användarens webbläsare. Servern behöver bara kunna nå GitHub; om den behöver en proxy för det anger du GITHUB_SYNC_PROXY_URL. GitHub anropar aldrig din instans: ett projekt synkroniseras bara när en användare synkroniserar det i redigeraren.

Länkningen av mitt GitHub-konto misslyckas eller skickar tillbaka mig utan att länka

Svar: Kontrollera följande i tur och ordning:

• Öppna Overleaf på exakt den adress som anges i OVERLEAF_SITE_URL. GitHub skickar tillbaka dig till ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, och din inloggning finns bara på den adress du började från, så en annan värd, IP-adress eller port hamnar på inloggningssidan eller på ”Restricted, sorry you don’t have permission to load this page”.
• OAuth-appens Authorization callback URL måste vara ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, med samma schema, värd och port.
• En felsida med Failed to obtain access token from Git server betyder att GitHub inte returnerade någon token: kontrollera GITHUB_SYNC_CLIENT_ID och GITHUB_SYNC_CLIENT_SECRET, och att servern kan nå GitHub. Kör bin/logs web för att se hela felet.

Efter att du har ändrat config/variables.env kör du bin/up för att återskapa containrarna.

Importen av ett repositorium misslyckas med ”EmptyZipFileError: empty_zip_file” eller ”unzip failed”

Svar: Overleaf importerar zip-arkivet för den senaste commiten på repositoriets standardgren, och felet betyder att arkivet inte innehåller någon fil som Overleaf kan importera. Kontrollera standardgrenen på GitHub:

• Den innehåller projektfilerna, inte bara filer som Overleaf hoppar över vid import: dotfiler som .gitignore och .gitmodules (.latexmkrc behålls) samt byggfiler som *.aux, *.log, *.bbl, *.synctex.gz, *.doc och *.docx.
• Filerna ligger inte bara i Git-submoduler. GitHubs arkiv lämnar submoduler som tomma mappar.
• Filerna du förväntar dig finns på standardgrenen, inte på en annan gren. Importen använder alltid standardgrenen.

Importen av ett repositorium misslyckas med ”connect ECONNREFUSED” till ”sharelatex:3054”

Svar: V1_HISTORY_URL är satt till http://sharelatex:3054, ett värde som äldre versioner av den här dokumentationen angav. Port 3054 är tjänsten project-history, som bara lyssnar inuti containern, medan V1_HISTORY_URL måste peka på history-v1. Overleaf sparar varje binärfil (bilder, PDF-filer) i det importerade repositoriet till history-v1, så importen misslyckas; att ladda upp en sådan fil i redigeraren misslyckas på samma sätt. I din docker-compose.yml sätter du V1_HISTORY_URL: "http://sharelatex:3100/api" för tjänsten sharelatex (se Git-integration) och återskapar containern. Toolkit sätter redan detta värde; kontrollera att docker-compose.override.yml inte åsidosätter det.