GitHub-synkronisering

Lad brugere synkronisere deres projekter med repositories på GitHub eller GitHub Enterprise.

Denne funktion er udviklet af ayaka-notes/ayakaleaf-pro og tilpasset af yu-i-i/overleaf-cep. Den er introduceret i v6.2.0 og senere. Den er stadig i betastatus. Vi har brug for din feedback, hvis du oplever problemer.

​

Opsætning af GitHub-synkronisering

Du skal først aktivere git-bridge, før du kan bruge GitHub-synkronisering.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Gå til udviklerindstillinger for at oprette din GitHub OAuth-applikation, og kopiér dit CLIENT_ID og din SECRET.

Bemærk: Når du opretter OAuth-appen, skal du angive ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback i Authorization callback URL. Ayakaleaf Pro bygger den samme adresse ud fra OVERLEAF_SITE_URL, så der er intet at sætte for den i config/variables.env.

Tilføj derefter følgende indstillinger til dine Overleaf-miljøvariabelfiler.

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

Før du konfigurerer GitHub OAuth-callback-URL’en, skal du sikre dig, at OVERLEAF_SITE_URL er sat korrekt.

Hvis du befinder dig i en region med begrænset netværksadgang, kan det være nødvendigt at konfigurere en proxy for at få adgang til GitHub. Sæt følgende miljøvariabel: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Sørg for, at din brug af en proxy overholder lokale love og regler.

GITHUB_SYNC_PROXY_URL skal være en almindelig HTTP/HTTPS-videresendelsesproxy (f.eks. HTTP-porten i Clash). GitHub-downloadspejle som gh-proxy.org understøttes ikke.

Brug ikke 127.0.0.1 som proxyvært. Hvis proxyen kører på værtsserveren, skal du bruge serverens LAN-IP-adresse (f.eks. 192.168.1.xx) og sikre dig, at proxyen er konfigureret til at acceptere forbindelser fra enheder på det lokale netværk.

​

GitHub Enterprise

Understøttelse af GitHub Enterprise er introduceret i v6.3.1 og senere. Tidligere versioner forbinder kun til github.com, og variablerne nedenfor har ingen effekt.

Som standard forbinder GitHub-synkronisering til github.com. For at bruge GitHub Enterprise Server (selvhostet) eller GitHub Enterprise Cloud med dataresidens (GHE.com) skal du sætte GITHUB_SYNC_URL til webadressen for din instans, den adresse du åbner repositories med i browseren.

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

REST- og GraphQL-API-endpoints udledes af GITHUB_SYNC_URL på samme måde, som GitHub CLI gør det:

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 (alle andre)	https://HOST/api/v3	https://HOST/api/graphql

Sæt kun API-endpoints, hvis din instans udstiller dem et andet sted, for eksempel bag en API-gateway:

Variabel	Standard
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Udledes af GITHUB_SYNC_URL, se tabellen ovenfor
GITHUB_SYNC_GRAPHQL_URL	Udledes af GITHUB_SYNC_API_URL, når den er sat (/api/v3 bliver til /api/graphql, ellers tilføjes /graphql), ellers af GITHUB_SYNC_URL

• Opret OAuth-applikationen på din enterprise-instans (Settings → Developer settings → OAuth Apps). En applikation fra github.com virker ikke der. Callback-URL’en er den samme: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL er kun webadressen. Sæt den ikke til en API-adresse som https://api.github.com eller https://HOST/api/v3, og tilføj ikke en organisationssti.
• Alle tre adresser skal pege på den samme GitHub-instans.

Hvis din instans bruger et certifikat fra en privat CA, skal du montere CA-certifikatet i containeren og pege NODE_EXTRA_CA_CERTS på det, f.eks. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Forbundne konti og projekter hører til den instans, de blev forbundet med. Før du skifter GITHUB_SYNC_URL til en anden instans, skal du bede brugerne om at fjerne forbindelsen til deres GitHub-konto og projekter.

​

Hvem kan forbinde og synkronisere

Ligesom på Overleaf Cloud kan kun projektejeren forbinde et projekt med et GitHub-repository. Når det er forbundet, kan alle samarbejdspartnere med redigeringsadgang synkronisere det.

Handling	Hvem kan gøre det
Eksportere et projekt til et nyt GitHub-repository	Projektejeren
Importere et GitHub-repository til et nyt projekt	Enhver bruger, som bliver ejer af det nye projekt
Pull, push og merge af et forbundet projekt	Ejeren og samarbejdspartnere med redigeringsadgang
Fjerne forbindelsen mellem et projekt og dets repository	Projektejeren

• Overleaf kommunikerer med GitHub via GitHub-kontoen for den bruger, der synkroniserer, så alle samarbejdspartnere, der synkroniserer, forbinder deres egen GitHub-konto og skal have tilladelse til at pushe til repositoryets standardbranch.
• Samarbejdspartnere med kun læseadgang kan ikke bruge GitHub-synkronisering for projektet.

​

Spørgsmål og svar

Hvordan forbinder jeg et projekt med GitHub og synkroniserer det?

Svar: Åbn Integrations i editoren, og klik på GitHub. Hvis din GitHub-konto endnu ikke er forbundet, skal du først klikke på Link to your GitHub account. Under Export Project to GitHub skal du angive et repositorynavn, vælge Private under Repository visibility og klikke på Create a GitHub repository.

Derefter åbner det samme kort Sync with GitHub, som viser de nye commits i GitHub. Klik på Sync for at committe dine Overleaf-ændringer til standardbranchen og hente GitHub-ændringerne ind i projektet. Synkroniseringen går begge veje, men kører kun, når nogen klikker på Sync; der er ingen planlagt synkronisering. Når begge sider er ændret, merger Overleaf via en midlertidig branch med navnet overleaf-YYYY-MM-DD-HHMMSS. Hvis den merge har en konflikt, skal du selv merge branchen i GitHub og derefter klikke på I have manually merged. Continue.

Kan jeg force-pushe til standardbranchen?

Svar: Det anbefaler vi ikke. Overleaf registrerer et force push, advarer om det og overtager den omskrevne branch, hvorefter ændringerne foretaget i Overleaf siden sidste synkronisering merges. For at undgå overraskelser bør du beskytte standardbranchen mod force push i repositoryets indstillinger.

Kan jeg omdøbe standardbranchen i et forbundet projekt?

Svar: Lad venligst være. Overleaf fortsætter med at synkronisere med den branch, projektet blev forbundet med. For at synkronisere med en anden branch skal du fjerne forbindelsen til projektet og derefter importere repositoryet i et nyt projekt, som bruger den aktuelle standardbranch.

GitHub-synkronisering viser »Something wrong with GitHub request«

Svar: Denne besked betyder, at serveren ikke kunne nå GitHub, for eksempel på grund af et netværks-, DNS-, TLS- eller proxyproblem. Kør bin/logs web for at se den fulde fejl. Hvis serveren har brug for en proxy for at nå GitHub, skal du sætte GITHUB_SYNC_PROXY_URL.

Skal jeg deaktivere »Expire user access tokens« i GitHub OAuth-appen?

Svar: Ja. GitHub-synkronisering fornyer ikke udløbne tokens. Med udløbende tokens aktiveret skal brugerne forbinde GitHub igen, hver gang deres token udløber.

Skal min instans kunne nås fra internettet?

Svar: Nej. Tilknytning af en konto sker via brugerens browser, så OAuth-callback-adressen behøver kun at kunne åbnes i brugerens browser. Serveren skal kun kunne nå GitHub; hvis den har brug for en proxy til det, skal du sætte GITHUB_SYNC_PROXY_URL. GitHub kalder aldrig din instans: et projekt synkroniseres kun, når en bruger synkroniserer det i editoren.

Tilknytning af min GitHub-konto mislykkes eller sender mig tilbage uden tilknytning

Svar: Kontrollér disse punkter i rækkefølge:

• Åbn Overleaf på præcis den adresse, der er sat i OVERLEAF_SITE_URL. GitHub sender dig tilbage til ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, og dit login findes kun på den adresse, du startede fra, så en anden vært, IP-adresse eller port ender på login-siden eller på »Restricted, sorry you don’t have permission to load this page«.
• OAuth-appens Authorization callback URL skal være ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback med samme skema, vært og port.
• En fejlside med Failed to obtain access token from Git server betyder, at GitHub ikke returnerede et token: kontrollér GITHUB_SYNC_CLIENT_ID og GITHUB_SYNC_CLIENT_SECRET, og at serveren kan nå GitHub. Kør bin/logs web for at se den fulde fejl.

Når du har ændret config/variables.env, skal du køre bin/up for at genoprette containerne.

Import af et repository mislykkes med »EmptyZipFileError: empty_zip_file« eller »unzip failed«

Svar: Overleaf importerer zip-arkivet for den seneste commit på repositoryets standardbranch, og denne fejl betyder, at arkivet ikke indeholder nogen fil, som Overleaf kan importere. Kontrollér standardbranchen på GitHub:

• Den indeholder projektfilerne og ikke kun filer, som Overleaf springer over ved import: dotfiler som .gitignore og .gitmodules (.latexmkrc bevares) og buildfiler som *.aux, *.log, *.bbl, *.synctex.gz, *.doc og *.docx.
• Filerne ligger ikke kun i Git-submoduler. GitHubs arkiv efterlader submoduler som tomme mapper.
• De filer, du forventer, ligger på standardbranchen og ikke på en anden branch. Import bruger altid standardbranchen.

Import af et repository mislykkes med »connect ECONNREFUSED« til »sharelatex:3054«

Svar: V1_HISTORY_URL er sat til http://sharelatex:3054, en værdi, som ældre versioner af denne dokumentation angav. Port 3054 er tjenesten project-history, som kun lytter inde i containeren, mens V1_HISTORY_URL skal pege på history-v1. Overleaf gemmer alle binære filer (billeder, PDF’er) fra det importerede repository i history-v1, så importen mislykkes; upload af en sådan fil i editoren mislykkes på samme måde. Sæt i din docker-compose.yml V1_HISTORY_URL: "http://sharelatex:3100/api" på tjenesten sharelatex (se Git-integration), og genopret containeren. Toolkit sætter allerede denne værdi; kontrollér, at docker-compose.override.yml ikke tilsidesætter den.