Gitea-synkronointi

Tämän ominaisuuden on kehittänyt ayaka-notes/ayakaleaf-pro. Se on otettu käyttöön versiossa v6.3.2 varhaisena esiversiona, ja se julkaistaan virallisesti versiossa v6.4.0, joten sen määritykset ja toiminta voivat vielä muuttua. Tarvitsemme palautettasi, jos kohtaat ongelmia.

Gitea-synkronointi toimii samalla tavalla kuin GitHub-synkronointi ja GitLab-synkronointi: käyttäjät linkittävät Gitea-tilinsä, vievät projekteja uusiin Gitea-repositorioihin, tuovat Gitea-repositorioita ja synkronoivat muutoksia molempiin suuntiin. Se toimii Gitean version 1.23 tai uudemman kanssa, gitea.comissa tai omassa instanssissasi.

​

Gitea-synkronoinnin määrittäminen

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Luo OAuth2-sovellus Gitea-instanssiisi kohdassa Settings → Applications → Manage OAuth2 applications (tai Site Administration → Integrations → Applications, jos haluat koko instanssin laajuisen sovelluksen):

• Application name: esim. Overleaf, käyttäjät näkevät sen valtuuttaessaan sovelluksen
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: valittuna

Kopioi Client ID ja Client Secret ja lisää sitten seuraavat asetukset Overleafin ympäristömuuttujatiedostoihin.

config/variables.env

# used to encrypt the user's Gitea access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITEA_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
# (Optional) GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808

Varmista ennen Gitean uudelleenohjaus-URI:n määrittämistä, että OVERLEAF_SITE_URL on asetettu oikein.

Overleaf pyytää kaikki synkronoinnin tarvitsemat oikeudet, kun käyttäjä linkittää tilin, joten käyttäjien ei koskaan tarvitse linkittää uudelleen puuttuvan oikeuden vuoksi:

Laajuus (scope)	Käyttötarkoitus
write:repository	Repositoriot, niiden tiedostot (mukaan lukien CI-työnkulut kohteessa .gitea/workflows), haarat ja pull requestit
write:user	Käyttäjän repositorion luominen vietäessä (Gitea vaatii sen kutsulle POST /user/repos)
write:organization	Käyttäjän organisaatioiden listaaminen ja organisaation repositorion luominen vietäessä

Gitea näyttää nämä laajuudet, kun käyttäjä valtuuttaa sovelluksen, ja rajoittaa tunnuksen niihin.

Gitean käyttöoikeustunnukset (access token) vanhenevat tunnin kuluttua ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf uudistaa ne päivitystunnuksella (refresh token), jonka Gitea myöntää niiden mukana, myös silloin, kun Gitea mitätöi päivitystunnukset käytön yhteydessä (INVALIDATE_REFRESH_TOKENS = true), joten käyttäjien linkitys säilyy, kunnes he purkavat linkityksen tai peruuttavat sovelluksen käyttöoikeuden Giteassa.

​

Gitea-instanssisi

Aseta GITEA_SYNC_URL instanssisi verkko-osoitteeksi, eli sen ROOT_URL-arvoksi, jolla avaat repositorioita selaimessa. REST API -osoite johdetaan siitä:

Muuttuja	Oletusarvo
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Myös alipolun alla tarjottu Gitea toimii, esim. GITEA_SYNC_URL=https://example.com/gitea. Aseta GITEA_SYNC_API_URL vain, jos instanssisi tarjoaa API:n muualla, esimerkiksi API-yhdyskäytävän takana.

• Luo OAuth2-sovellus siihen instanssiin, jonka asetit GITEA_SYNC_URL-muuttujaan. Toisessa instanssissa luotu sovellus ei toimi.
• GITEA_SYNC_URL on pelkkä verkko-osoite. Älä lisää siihen /api/v1-polkua tai käyttäjän tai organisaation polkua.
• Overleaf tekee commitit Gitean tiedosto-API:lla, joka edellyttää verkkoeditoria: pidä [repository.editor] käytössä (oletus).

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/gitea-ca.pem.

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

Jos olet alueella, jolla verkkoyhteyksiä on rajoitettu, sinun on ehkä määritettävä välityspalvelin Gitean käyttämiseksi. Aseta seuraava ympäristömuuttuja: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Sen on oltava tavallinen HTTP/HTTPS-välityspalvelin (forward proxy), eikä se saa käyttää osoitetta 127.0.0.1.

​

Kuka voi linkittää ja synkronoida

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

Toiminto	Kuka voi tehdä sen
Projektin vieminen uuteen Gitea-repositorioon	Projektin omistaja
Gitea-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 Gitean kanssa synkronoivan käyttäjän Gitea-tilillä, joten jokainen synkronoiva yhteistyökumppani linkittää oman Gitea-tilinsä, ja hänellä on oltava oikeus pushata repositorion oletushaaraan.
• Pelkät katseluoikeudet omaavat yhteistyökumppanit eivät voi käyttää projektin Gitea-synkronointia.
• Tilin linkityksen purkaminen Overleafissa unohtaa sen tunnuksen. Giteassa ei ole API:a sen peruuttamiseen, joten peruuta halutessasi myös valtuutus Giteassa kohdassa Settings → Applications.

​

Miten synkronointi toimii Gitean kanssa

• Käyttöoikeudet: käyttäjillä on oltava oikeus pushata linkitetyn repositorion oletushaaraan. Jos haarasuojaussääntö ei salli käyttäjän pushata siihen, Overleaf pyytää häntä ottamaan yhteyttä projektin omistajaan, kuten repositorion kohdalla, johon käyttöoikeus on menetetty.
• Yhdistäminen: kun projektia on muutettu sekä Overleafissa että Giteassa, Overleaf tekee muutoksistaan commitin väliaikaiseen haaraan nimeltä overleaf-YYYY-MM-DD-HHMMSS ja yhdistää sen pull requestin kautta repositorion oletusyhdistämistyylillä, koska Giteassa ei ole API:a haarojen yhdistämiseen ilman sellaista. Yhdistämisen jälkeen Overleaf poistaa väliaikaisen haaran. Yhdistetty pull request jää repositorioon merkinnäksi.
• Yhdistämissäännöt: Overleaf ei koskaan ohita repositorion haarasuojausta. Jos pull requestissa on ristiriita tai se vaatii hyväksyntöjä tai läpäistyjä tilatarkistuksia, se jää avoimeksi ja Overleaf pyytää käyttäjää yhdistämään sen Giteassa ja jatkamaan sitten synkronointia.
• CI-työnkulut: Overleaf ei näytä pistetiedostoja, kuten .gitea/workflows/, vaan jättää ne repositorioon sellaisinaan. Overleafin commitit käynnistävät Gitea Actionsin kuten mikä tahansa muu commit.

​

Q&A

Voinko tehdä force pushin oletushaaraan?

Vastaus: Pidä force pushit oletushaaraan poissa käytöstä, esim. haarasuojaussäännöllä. Overleaf pystyy ottamaan uudelleenkirjoitetun haaran haltuunsa, mutta Gitea-synkronointi on suunniteltu oletushaaralle, jonka historia vain kasvaa.

Voinko nimetä linkitetyn projektin oletushaaran uudelleen?

Vastaus: Et. Overleaf jatkaa synkronointia sen haaran kanssa, johon projekti linkitettiin, joten synkronoinnit epäonnistuvat, kun haara nimetään uudelleen tai poistetaan. Jos haluat synkronoida toisen haaran kanssa, pura projektin linkitys ja tuo sitten repositorio uuteen projektiin, joka käyttää nykyistä oletushaaraa.

Tukeeko Gitea-synkronointi Git LFS:ää?

Vastaus: Ei. Overleaf-projektit eivät tue Git Large File Storagea. Git LFS:n seuraamat tiedostot näkyvät Overleafissa LFS-osoitintiedostoina eivätkä niiden sisältönä. Tee kuvista ja PDF-tiedostoista commit suoraan repositorioon.

Toimiiko se SHA-256-repositorioiden kanssa?

Vastaus: Ei vielä. Overleaf vertaa tiedostoja niiden SHA-1-tunnisteiden perusteella, joten SHA-256-objektimuodolla luodussa repositoriossa jokainen pull kirjoittaa kaikki tiedostot uudelleen, myös muuttumattomat. Mitään ei menetetä, mutta käytä oletusarvoista SHA-1-muotoa.

Toimiiko se Forgejon kanssa?

Vastaus: Gitea-synkronointi on rakennettu ja testattu vain Giteaa vasten.