Gitea-synkronisering

Denne funksjonen er utviklet av ayaka-notes/ayakaleaf-pro. Den er introdusert i v6.3.2 som en tidlig forhåndsversjon (early preview) og blir offisielt lansert i v6.4.0, så konfigurasjonen og virkemåten kan fortsatt endres. Vi trenger tilbakemeldingen din hvis du får problemer.

Gitea-synkronisering fungerer som GitHub-synkronisering og GitLab-synkronisering: brukere kobler til Gitea-kontoen sin, eksporterer prosjekter til nye Gitea-repositorier, importerer Gitea-repositorier og synkroniserer endringer i begge retninger. Det fungerer med Gitea 1.23 eller nyere, på gitea.com eller på din egen instans.

​

Sette opp Gitea-synkronisering

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Opprett en OAuth2-applikasjon på Gitea-instansen din, under Settings → Applications → Manage OAuth2 applications (eller Site Administration → Integrations → Applications for en applikasjon for hele instansen):

• Application name: f.eks. Overleaf, brukerne ser dette navnet når de autoriserer applikasjonen
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: avkrysset

Kopier Client ID og Client Secret, og legg deretter til følgende innstillinger i Overleaf-miljøvariabelfilene dine.

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

Før du konfigurerer redirect-URI-en for Gitea, må du sørge for at OVERLEAF_SITE_URL er riktig satt.

Overleaf ber om alt en synkronisering trenger når brukeren kobler til kontoen, slik at brukerne aldri trenger å koble til på nytt på grunn av en manglende tillatelse:

Omfang	Brukes til
write:repository	Repositorier, filene deres (inkludert CI-arbeidsflyter under .gitea/workflows), grener og pull requests
write:user	Oppretting av et repositorium for brukeren ved eksport (Gitea krever det for POST /user/repos)
write:organization	Oppføring av brukerens organisasjoner og oppretting av et repositorium i en av dem ved eksport

Gitea viser disse omfangene når brukeren autoriserer applikasjonen, og begrenser tokenet til dem.

Tilgangstokener fra Gitea utløper etter én time ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf fornyer dem med refresh-tokenet som Gitea utsteder sammen med dem, også når Gitea forbruker refresh-tokener ved bruk (INVALIDATE_REFRESH_TOKENS = true), slik at brukerne forblir tilkoblet til de kobler fra eller trekker tilbake applikasjonen i Gitea.

​

Din Gitea-instans

Sett GITEA_SYNC_URL til nettadressen til instansen din, dens ROOT_URL, den du åpner repositorier med i nettleseren. REST-API-et utledes fra denne:

Variabel	Standard
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Gitea som leveres under en understi, fungerer også, f.eks. GITEA_SYNC_URL=https://example.com/gitea. Sett bare GITEA_SYNC_API_URL når instansen din leverer API-et et annet sted, for eksempel bak en API-gateway.

• Opprett OAuth2-applikasjonen på instansen du angir i GITEA_SYNC_URL, en applikasjon fra en annen instans fungerer ikke.
• GITEA_SYNC_URL er kun nettadressen. Ikke legg til /api/v1 eller en bruker- eller organisasjonssti.
• Overleaf committer med filer-API-et i Gitea, som krever webeditoren: la [repository.editor] være aktivert (standard).

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

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

Hvis du befinner deg i en region med begrenset nettverkstilgang, kan det hende du må konfigurere en proxy for å få tilgang til Gitea. Sett følgende miljøvariabel: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Det må være en vanlig HTTP/HTTPS-videresendingsproxy, og den må ikke bruke 127.0.0.1.

​

Hvem kan koble til og synkronisere

I likhet med Overleaf Cloud er det bare prosjekteieren som kan koble et prosjekt til et Gitea-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 Gitea-repositorium	Prosjekteieren
Importere et Gitea-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 Gitea via Gitea-kontoen til brukeren som synkroniserer, så alle samarbeidspartnere som synkroniserer, kobler til sin egen Gitea-konto og må ha tillatelse til å pushe til standardgrenen i repositoriet.
• Samarbeidspartnere med kun lesetilgang kan ikke bruke Gitea-synkronisering for prosjektet.
• Når du kobler fra kontoen i Overleaf, glemmes tokenet. Gitea har ikke noe API for å tilbakekalle det, så trekk også tilbake tillatelsen under Settings → Applications i Gitea hvis du ønsker det.

​

Slik fungerer synkronisering med Gitea

• Tillatelser: brukere må ha tillatelse til å pushe til standardgrenen i det koblede repositoriet. Når en grenbeskyttelsesregel ikke lar brukeren pushe til den, ber Overleaf dem kontakte prosjekteieren, som for et repositorium de har mistet tilgang til.
• Sammenslåing: når et prosjekt er endret både i Overleaf og i Gitea, committer Overleaf endringene sine til en midlertidig gren kalt overleaf-YYYY-MM-DD-HHMMSS og slår den sammen via en pull request med repositoriets standard sammenslåingsstil, fordi Gitea ikke har noe API for å slå sammen grener uten. Etter sammenslåingen sletter Overleaf den midlertidige grenen. Den sammenslåtte pull requesten blir liggende i repositoriet som dokumentasjon.
• Regler for sammenslåing: Overleaf omgår aldri repositoriets grenbeskyttelse. Når pull requesten har en konflikt, eller krever godkjenninger eller vellykkede statuskontroller, forblir den åpen, og Overleaf ber brukeren slå den sammen i Gitea og deretter fortsette synkroniseringen.
• CI-arbeidsflyter: Overleaf viser ikke punktumfiler som .gitea/workflows/, og lar dem være som de er i repositoriet. Commits fra Overleaf starter Gitea Actions som alle andre commits.

​

Q&A

Kan jeg force-pushe til standardgrenen?

Svar: La force push til standardgrenen være deaktivert, f.eks. med en grenbeskyttelsesregel. Overleaf kan overta en omskrevet gren, men Gitea-synkronisering er laget for en standardgren der historikken bare vokser.

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

Svar: Nei. Overleaf fortsetter å synkronisere med grenen prosjektet ble koblet til, så synkroniseringer mislykkes når den grenen får nytt navn eller fjernes. For å synkronisere med en annen gren kobler du fra prosjektet og importerer deretter repositoriet til et nytt prosjekt, som bruker den gjeldende standardgrenen.

Støtter Gitea-synkronisering Git LFS?

Svar: Nei. Overleaf-prosjekter støtter ikke Git Large File Storage. Filer som spores av Git LFS, vises i Overleaf som LFS-pekerfiler, ikke med innholdet sitt. Commit heller bilder og PDF-er direkte til repositoriet.

Fungerer det med SHA-256-repositorier?

Svar: Ikke ennå. Overleaf sammenligner filer etter SHA-1-ID-ene deres, så i et repositorium som er opprettet med objektformatet SHA-256, skriver hver pull om alle filer, også uendrede. Ingenting går tapt, men bruk standardformatet SHA-1.

Fungerer det med Forgejo?

Svar: Gitea-synkronisering er bygget og testet kun mot Gitea.