GitHub-synkronisering

La brukere synkronisere prosjektene sine med repositorier på GitHub eller GitHub Enterprise.

Denne funksjonen er utviklet av ayaka-notes/ayakaleaf-pro og modifisert av yu-i-i/overleaf-cep. Den er introdusert fra og med v6.2.0. Den er fortsatt i betastatus. Vi trenger tilbakemeldingen din hvis du får problemer.

​

Sette opp GitHub-synkronisering

Du må aktivere git-bridge før du kan bruke GitHub-synkronisering.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Gå til utviklerinnstillingene for å opprette GitHub OAuth-applikasjonen din, og kopier CLIENT_ID og SECRET.

Merk: når du oppretter OAuth-appen, skriver du inn ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback i Authorization callback URL. Ayakaleaf Pro bygger den samme adressen fra OVERLEAF_SITE_URL, så det er ingenting å angi for den i config/variables.env.

Legg deretter til følgende innstillinger i Overleaf-miljøvariabelfilene dine.

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 callback-URL-en for GitHub OAuth, må du sørge for at OVERLEAF_SITE_URL er riktig satt.

Hvis du befinner deg i en region med begrenset nettverkstilgang, kan det hende du må konfigurere en proxy for å få tilgang til GitHub. Sett følgende miljøvariabel: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Sørg for at bruken av proxy er i samsvar med lokale lover og forskrifter.

GITHUB_SYNC_PROXY_URL må være en vanlig HTTP/HTTPS-videresendingsproxy (for eksempel HTTP-porten til Clash). GitHub-nedlastingsspeil som gh-proxy.org støttes ikke.

Ikke bruk 127.0.0.1 som proxy-vert. Hvis proxyen kjører på vertsserveren, bruker du serverens LAN-IP-adresse (som 192.168.1.xx) og sørger for at proxyen er konfigurert til å godta tilkoblinger fra enheter på det lokale nettverket.

​

GitHub Enterprise

Støtte for GitHub Enterprise er introdusert fra og med v6.3.1. Tidligere versjoner kobler bare til github.com, og variablene nedenfor har ingen effekt.

Som standard kobler GitHub-synkronisering til github.com. For å bruke GitHub Enterprise Server (selvdriftet) eller GitHub Enterprise Cloud med datalagring i bestemt region (GHE.com), setter du GITHUB_SYNC_URL til nettadressen til instansen din, den du åpner repositorier med i nettleseren.

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-endepunktene utledes fra GITHUB_SYNC_URL på samme måte som GitHub CLI gjø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 (alle andre)	https://HOST/api/v3	https://HOST/api/graphql

Sett bare API-endepunktene når instansen din leverer dem et annet sted, for eksempel bak en API-gateway:

Variabel	Standard
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Utledet fra GITHUB_SYNC_URL, se tabellen ovenfor
GITHUB_SYNC_GRAPHQL_URL	Utledet fra GITHUB_SYNC_API_URL når den er satt (/api/v3 blir /api/graphql, ellers legges /graphql til), ellers fra GITHUB_SYNC_URL

• Opprett OAuth-applikasjonen på enterprise-instansen din (Settings → Developer settings → OAuth Apps), en applikasjon fra github.com fungerer ikke der. Callback-URL-en er den samme: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL er kun nettadressen. Ikke sett den til en API-adresse som https://api.github.com eller https://HOST/api/v3, og ikke legg til en organisasjonssti.
• Alle tre adressene må peke til den samme GitHub-instansen.

Hvis instansen din bruker et sertifikat fra en privat CA, monterer du CA-sertifikatet i containeren og lar NODE_EXTRA_CA_CERTS peke til det, f.eks. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Koblede kontoer og prosjekter tilhører instansen de ble koblet til. Før du bytter GITHUB_SYNC_URL til en annen instans, må du be brukerne om å koble fra GitHub-kontoen og prosjektene sine.

​

Hvem kan koble til og synkronisere

I likhet med Overleaf Cloud er det bare prosjekteieren som kan koble et prosjekt til et GitHub-repositorium. Når det er koblet til, kan alle samarbeidspartnere med redigeringstilgang synkronisere det.

Handling	Hvem kan gjøre det
Eksportere et prosjekt til et nytt GitHub-repositorium	Prosjekteieren
Importere et GitHub-repositorium til et nytt prosjekt	Enhver bruker, som blir eier av det nye prosjektet
Hente, pushe og slå sammen et koblet prosjekt	Eieren og samarbeidspartnere med redigeringstilgang
Koble et prosjekt fra repositoriet sitt	Prosjekteieren

• Overleaf kommuniserer med GitHub via GitHub-kontoen til brukeren som synkroniserer, så alle samarbeidspartnere som synkroniserer, kobler til sin egen GitHub-konto og må ha tillatelse til å pushe til standardgrenen i repositoriet.
• Samarbeidspartnere med kun lesetilgang kan ikke bruke GitHub-synkronisering for prosjektet.

​

Q&A

Hvordan kobler jeg et prosjekt til GitHub og synkroniserer det?

Svar: Åpne Integrations i editoren og klikk GitHub. Hvis GitHub-kontoen din ikke er koblet til ennå, klikker du først Link to your GitHub account. I Export Project to GitHub skriver du inn et repositorinavn, velger Private under Repository visibility og klikker Create a GitHub repository.

Deretter åpner det samme kortet Sync with GitHub, som viser de nye commitene i GitHub. Klikk Sync for å committe Overleaf-endringene dine til standardgrenen og hente GitHub-endringene inn i prosjektet. Synkroniseringen går begge veier, men kjører bare når noen klikker Sync; det finnes ingen planlagt synkronisering. Når begge sider er endret, fletter Overleaf via en midlertidig gren med navnet overleaf-YYYY-MM-DD-HHMMSS. Hvis den flettingen har en konflikt, fletter du grenen i GitHub selv og klikker deretter I have manually merged. Continue.

Kan jeg force-pushe til standardgrenen?

Svar: Vi anbefaler det ikke. Overleaf oppdager en force push, advarer om den og overtar den omskrevne grenen, og slår sammen endringene som er gjort i Overleaf siden forrige synkronisering. For å unngå overraskelser bør du beskytte standardgrenen mot force push i innstillingene for repositoriet.

Kan jeg gi nytt navn til standardgrenen i et koblet prosjekt?

Svar: Vennligst ikke gjør det. Overleaf fortsetter å synkronisere med grenen prosjektet ble koblet til. For å synkronisere med en annen gren kobler du fra prosjektet og importerer deretter repositoriet til et nytt prosjekt, som bruker den gjeldende standardgrenen.

GitHub-synkronisering viser «Something wrong with GitHub request»

Svar: Denne meldingen betyr at serveren ikke kunne nå GitHub, for eksempel på grunn av et problem med nettverk, DNS, TLS eller proxy. Kjør bin/logs web for å se hele feilen. Hvis serveren trenger en proxy for å nå GitHub, setter du GITHUB_SYNC_PROXY_URL.

Bør jeg deaktivere «Expire user access tokens» i GitHub OAuth-appen?

Svar: Ja. GitHub-synkroniseringen fornyer ikke utløpte tokener. Med utløpende tokener aktivert må brukerne koble til GitHub på nytt hver gang tokenet deres utløper.

Må instansen min være tilgjengelig fra internett?

Svar: Nei. Kobling av en konto går gjennom brukerens nettleser, så OAuth-callback-adressen trenger bare å kunne åpnes i brukerens nettleser. Serveren trenger bare å nå GitHub; hvis den trenger en proxy til det, setter du GITHUB_SYNC_PROXY_URL. GitHub kaller aldri instansen din: et prosjekt synkroniseres bare når en bruker synkroniserer det i editoren.

Kobling av GitHub-kontoen min mislykkes eller sender meg tilbake uten kobling

Svar: Kontroller disse i rekkefølge:

• Åpne Overleaf på nøyaktig den adressen som er satt i OVERLEAF_SITE_URL. GitHub sender deg tilbake til ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, og innloggingen din finnes bare på adressen du startet fra, så en annen vert, IP-adresse eller port ender på innloggingssiden eller på «Restricted, sorry you don’t have permission to load this page».
• Authorization callback URL for OAuth-appen må være ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, med samme skjema, vert og port.
• En feilside med Failed to obtain access token from Git server betyr at GitHub ikke returnerte et token: kontroller GITHUB_SYNC_CLIENT_ID og GITHUB_SYNC_CLIENT_SECRET, og at serveren kan nå GitHub. Kjør bin/logs web for å se hele feilen.

Etter at du har endret config/variables.env, kjører du bin/up for å gjenopprette containerne.

Import av et repositorium mislykkes med «EmptyZipFileError: empty_zip_file» eller «unzip failed»

Svar: Overleaf importerer zip-arkivet for den siste commiten på repositoriets standardgren, og denne feilen betyr at arkivet ikke inneholder noen fil som Overleaf kan importere. Kontroller standardgrenen på GitHub:

• Den inneholder prosjektfilene, ikke bare filer som Overleaf hopper over ved import: punktumfiler som .gitignore og .gitmodules (.latexmkrc beholdes), og byggefiler som *.aux, *.log, *.bbl, *.synctex.gz, *.doc og *.docx.
• Filene ligger ikke bare inne i Git-submoduler. GitHubs arkiv lar submoduler stå som tomme mapper.
• Filene du forventer, ligger på standardgrenen, ikke på en annen gren. Import bruker alltid standardgrenen.

Import av et repositorium mislykkes med «connect ECONNREFUSED» til «sharelatex:3054»

Svar: V1_HISTORY_URL er satt til http://sharelatex:3054, en verdi som eldre versjoner av denne dokumentasjonen oppga. Port 3054 er tjenesten project-history, som bare lytter inne i containeren, mens V1_HISTORY_URL må peke til history-v1. Overleaf lagrer hver binærfil (bilder, PDF-er) fra det importerte repositoriet i history-v1, så importen mislykkes; opplasting av en slik fil i editoren mislykkes på samme måte. I docker-compose.yml setter du V1_HISTORY_URL: "http://sharelatex:3100/api" på tjenesten sharelatex (se Git-integrasjon) og gjenoppretter containeren. Toolkit setter allerede denne verdien; kontroller at docker-compose.override.yml ikke overstyrer den.