GitHub-synkronointi

Anna käyttäjien synkronoida projektinsa GitHub- tai GitHub Enterprise -repositorioiden kanssa.

Tämän ominaisuuden on kehittänyt ayaka-notes/ayakaleaf-pro, ja sitä on muokannut yu-i-i/overleaf-cep. Se on otettu käyttöön versiosta v6.2.0 alkaen. Ominaisuus on vielä beta-vaiheessa. Tarvitsemme palautettasi, jos kohtaat ongelmia.

​

GitHub-synkronoinnin määrittäminen

Sinun on otettava git-bridge käyttöön ennen GitHub-synkronoinnin käyttämistä.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Siirry kehittäjäasetuksiin luodaksesi GitHub OAuth -sovelluksen ja kopioi sen CLIENT_ID ja SECRET.

Huomautus: kun luot OAuth-sovelluksen, syötä kenttään Authorization callback URL arvo ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback. Ayakaleaf Pro muodostaa saman osoitteen OVERLEAF_SITE_URL-muuttujasta, joten sitä varten ei tarvitse asettaa mitään tiedostoon config/variables.env.

Lisää sitten seuraavat asetukset Overleafin ympäristömuuttujatiedostoihin.

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

Varmista ennen GitHub OAuth -takaisinkutsun URL-osoitteen määrittämistä, että OVERLEAF_SITE_URL on asetettu oikein.

Jos olet alueella, jolla verkkoyhteyksiä on rajoitettu, sinun on ehkä määritettävä välityspalvelin GitHubin käyttämiseksi. Aseta seuraava ympäristömuuttuja: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Varmista, että välityspalvelimen käyttösi on paikallisten lakien ja määräysten mukaista.

GITHUB_SYNC_PROXY_URL -arvon on oltava tavallinen HTTP/HTTPS-välityspalvelin (forward proxy), esimerkiksi Clashin HTTP-portti. GitHubin latauspeilejä, kuten gh-proxy.org, ei tueta.

Älä käytä välityspalvelimen isäntänä osoitetta 127.0.0.1. Jos välityspalvelin toimii isäntäpalvelimella, käytä palvelimen lähiverkon IP-osoitetta (kuten 192.168.1.xx) ja varmista, että välityspalvelin on määritetty hyväksymään yhteydet lähiverkon laitteista.

​

GitHub Enterprise

GitHub Enterprise -tuki on otettu käyttöön versiosta v6.3.1 alkaen. Aiemmat versiot muodostavat yhteyden vain osoitteeseen github.com, eikä alla olevilla muuttujilla ole niissä vaikutusta.

Oletuksena GitHub-synkronointi muodostaa yhteyden osoitteeseen github.com. Jos haluat käyttää GitHub Enterprise Serveriä (itse isännöity) tai GitHub Enterprise Cloudia tietojen sijaintivaatimuksin (GHE.com), aseta GITHUB_SYNC_URL instanssisi verkko-osoitteeksi, eli siksi osoitteeksi, jolla avaat repositorioita selaimessa.

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- ja GraphQL-API-päätepisteet johdetaan GITHUB_SYNC_URL-arvosta samalla tavalla kuin GitHub CLI tekee:

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (oletus)	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 (mikä tahansa muu)	https://HOST/api/v3	https://HOST/api/graphql

Aseta API-päätepisteet vain, jos instanssisi tarjoaa ne muualla, esimerkiksi API-yhdyskäytävän takana:

Muuttuja	Oletusarvo
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Johdetaan GITHUB_SYNC_URL-arvosta, katso yllä oleva taulukko
GITHUB_SYNC_GRAPHQL_URL	Johdetaan GITHUB_SYNC_API_URL-arvosta, jos se on asetettu (/api/v3 muuttuu muotoon /api/graphql, muuten loppuun lisätään /graphql), muutoin GITHUB_SYNC_URL-arvosta

• Luo OAuth-sovellus enterprise-instanssiisi (Settings → Developer settings → OAuth Apps). github.com-palvelussa luotu sovellus ei toimi siellä. Takaisinkutsun URL-osoite on sama: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL on pelkkä verkko-osoite. Älä aseta sitä API-osoitteeksi, kuten https://api.github.com tai https://HOST/api/v3, äläkä lisää siihen organisaation polkua.
• Kaikkien kolmen osoitteen on osoitettava samaan GitHub-instanssiin.

Jos instanssisi käyttää yksityisen varmentajan (CA) myöntämää varmennetta, liitä CA-varmenne konttiin ja osoita NODE_EXTRA_CA_CERTS siihen, esim. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Linkitetyt tilit ja projektit kuuluvat siihen instanssiin, johon ne on linkitetty. Ennen kuin vaihdat GITHUB_SYNC_URL-arvon toiseen instanssiin, pyydä käyttäjiä purkamaan GitHub-tiliensä ja projektiensa linkitys.

​

Kuka voi linkittää ja synkronoida

Kuten Overleaf Cloudissa, vain projektin omistaja voi linkittää projektin GitHub-repositorioon. Kun linkitys on tehty, jokainen muokkausoikeudet omaava yhteistyökumppani voi synkronoida sen.

Toiminto	Kuka voi tehdä sen
Projektin vieminen uuteen GitHub-repositorioon	Projektin omistaja
GitHub-repositorion tuominen uuteen projektiin	Kuka tahansa käyttäjä, josta tulee uuden projektin omistaja
Linkitetyn projektin pull, push ja merge	Omistaja ja muokkausoikeudet omaavat yhteistyökumppanit
Projektin linkityksen purkaminen repositoriosta	Projektin omistaja

• Overleaf kommunikoi GitHubin kanssa synkronoivan käyttäjän GitHub-tilillä, joten jokainen synkronoiva yhteistyökumppani linkittää oman GitHub-tilinsä, ja hänellä on oltava oikeus pushata repositorion oletushaaraan.
• Pelkät katseluoikeudet omaavat yhteistyökumppanit eivät voi käyttää projektin GitHub-synkronointia.

​

Q&A

Miten linkitän projektin GitHubiin ja synkronoin sen?

Vastaus: Avaa editorissa Integrations ja napsauta GitHub. Jos GitHub-tiliäsi ei ole vielä linkitetty, napsauta ensin Link to your GitHub account. Kirjoita kohdassa Export Project to GitHub repositorion nimi, valitse Repository visibility -kohdasta Private ja napsauta Create a GitHub repository.

Sen jälkeen sama kortti avaa näkymän Sync with GitHub, jossa luetellaan GitHubin uudet commitit. Napsauta Sync, jolloin Overleafin muutokset commitoidaan oletushaaraan ja GitHubin muutokset tuodaan projektiin. Synkronointi toimii molempiin suuntiin, mutta se suoritetaan vain, kun joku napsauttaa Sync; ajastettua synkronointia ei ole. Kun molempia puolia on muutettu, Overleaf yhdistää muutokset väliaikaisen haaran kautta, jonka nimi on overleaf-YYYY-MM-DD-HHMMSS. Jos yhdistämisessä syntyy ristiriita, yhdistä haara itse GitHubissa ja napsauta sitten I have manually merged. Continue.

Voinko tehdä force pushin oletushaaraan?

Vastaus: Emme suosittele sitä. Overleaf havaitsee force pushin, varoittaa siitä ja ottaa uudelleenkirjoitetun haaran haltuunsa yhdistäen Overleafissa edellisen synkronoinnin jälkeen tehdyt muutokset. Yllätysten välttämiseksi suojaa oletushaara force pusheilta repositorion asetuksissa.

Voinko nimetä linkitetyn projektin oletushaaran uudelleen?

Vastaus: Älä tee niin. Overleaf jatkaa synkronointia sen haaran kanssa, johon projekti linkitettiin. Jos haluat synkronoida toisen haaran kanssa, pura projektin linkitys ja tuo sitten repositorio uuteen projektiin, joka käyttää nykyistä oletushaaraa.

GitHub-synkronointi näyttää viestin ”Something wrong with GitHub request”

Vastaus: Tämä viesti tarkoittaa, että palvelin ei tavoittanut GitHubia esimerkiksi verkko-, DNS-, TLS- tai välityspalvelinongelman vuoksi. Näet koko virheen komennolla bin/logs web. Jos palvelin tarvitsee välityspalvelimen tavoittaakseen GitHubin, aseta GITHUB_SYNC_PROXY_URL.

Pitäisikö GitHub OAuth -sovelluksen ”Expire user access tokens” -asetus poistaa käytöstä?

Vastaus: Kyllä. GitHub-synkronointi ei uusi vanhentuneita tunnuksia. Jos vanhenevat tunnukset ovat käytössä, käyttäjien on yhdistettävä GitHub uudelleen aina, kun heidän tunnuksensa vanhenee.

Täytyykö instanssini olla tavoitettavissa internetistä?

Vastaus: Ei. Tilin linkittäminen kulkee käyttäjän selaimen kautta, joten OAuth-takaisinkutsuosoitteen tarvitsee avautua vain käyttäjän selaimessa. Palvelimen tarvitsee tavoittaa vain GitHub; jos se tarvitsee siihen välityspalvelimen, aseta GITHUB_SYNC_PROXY_URL. GitHub ei koskaan ota yhteyttä instanssiisi: projekti synkronoidaan vain, kun käyttäjä synkronoi sen editorissa.

GitHub-tilini linkittäminen epäonnistuu tai palauttaa minut takaisin ilman linkitystä

Vastaus: Tarkista nämä järjestyksessä:

• Avaa Overleaf täsmälleen siitä osoitteesta, joka on asetettu muuttujaan OVERLEAF_SITE_URL. GitHub palauttaa sinut osoitteeseen ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, ja kirjautumisesi on olemassa vain siinä osoitteessa, josta aloitit, joten toinen isäntänimi, IP-osoite tai portti päätyy kirjautumissivulle tai viestiin ”Restricted, sorry you don’t have permission to load this page”.
• OAuth-sovelluksen Authorization callback URL -arvon on oltava ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback samalla skeemalla, isäntänimellä ja portilla.
• Virhesivu, jossa lukee Failed to obtain access token from Git server, tarkoittaa, että GitHub ei palauttanut tunnusta: tarkista GITHUB_SYNC_CLIENT_ID ja GITHUB_SYNC_CLIENT_SECRET sekä se, että palvelin tavoittaa GitHubin. Näet koko virheen komennolla bin/logs web.

Kun olet muuttanut tiedostoa config/variables.env, luo kontit uudelleen ajamalla bin/up.

Repositorion tuonti epäonnistuu virheeseen ”EmptyZipFileError: empty_zip_file” tai ”unzip failed”

Vastaus: Overleaf tuo repositorion oletushaaran viimeisimmän commitin zip-arkiston, ja tämä virhe tarkoittaa, ettei arkistossa ole yhtään tiedostoa, jonka Overleaf voi tuoda. Tarkista oletushaara GitHubissa:

• Se sisältää projektin tiedostot eikä vain tiedostoja, jotka Overleaf ohittaa tuonnissa: pistetiedostoja, kuten .gitignore ja .gitmodules (.latexmkrc säilytetään), sekä käännöstiedostoja, kuten *.aux, *.log, *.bbl, *.synctex.gz, *.doc ja *.docx.
• Tiedostot eivät ole pelkästään Git-alimoduulien sisällä. GitHubin arkisto jättää alimoduulit tyhjiksi kansioiksi.
• Odottamasi tiedostot ovat oletushaarassa eivätkä jossain toisessa haarassa. Tuonti käyttää aina oletushaaraa.

Repositorion tuonti epäonnistuu virheeseen ”connect ECONNREFUSED” kohteeseen ”sharelatex:3054”

Vastaus: V1_HISTORY_URL on asetettu arvoon http://sharelatex:3054, jota tämän dokumentaation vanhemmat versiot neuvoivat käyttämään. Portti 3054 on project-history-palvelu, joka kuuntelee vain kontin sisällä, kun taas V1_HISTORY_URL-muuttujan on osoitettava palveluun history-v1. Overleaf tallentaa tuodun repositorion jokaisen binaaritiedoston (kuvat, PDF-tiedostot) palveluun history-v1, joten tuonti epäonnistuu; tällaisen tiedoston lataaminen editorissa epäonnistuu samalla tavalla. Aseta docker-compose.yml-tiedostossasi sharelatex-palvelulle V1_HISTORY_URL: "http://sharelatex:3100/api" (katso Git-integraatio) ja luo kontti uudelleen. Toolkit asettaa tämän arvon jo; tarkista, ettei docker-compose.override.yml ohita sitä.