Gitea-synkronisering

Denne funktion er udviklet af ayaka-notes/ayakaleaf-pro. Den er introduceret i v6.3.2 som en tidlig forhåndsversion og vil blive officielt udgivet i v6.4.0, så dens konfiguration og adfærd kan stadig ændre sig. Vi har brug for din feedback, hvis du oplever problemer.

Gitea-synkronisering fungerer ligesom GitHub-synkronisering og GitLab-synkronisering: brugerne forbinder deres Gitea-konto, eksporterer projekter til nye Gitea-repositories, importerer Gitea-repositories og synkroniserer ændringer i begge retninger. Den fungerer med Gitea 1.23 eller nyere, på gitea.com eller på din egen instans.

​

Opsætning af Gitea-synkronisering

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Opret en OAuth2-applikation på din Gitea-instans under Settings → Applications → Manage OAuth2 applications (eller Site Administration → Integrations → Applications for en applikation, der gælder for hele instansen):

• Application name: f.eks. Overleaf, brugerne ser navnet, når de godkender applikationen
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: markeret

Kopiér Client ID og Client Secret, og tilføj derefter følgende indstillinger til dine Overleaf-miljøvariabelfiler.

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 Gitea-redirect-URI’en, skal du sikre dig, at OVERLEAF_SITE_URL er sat korrekt.

Overleaf anmoder om alt, hvad en synkronisering har brug for, når brugeren forbinder kontoen, så brugerne aldrig behøver at forbinde igen på grund af en manglende tilladelse:

Scope	Bruges til
write:repository	Repositories, deres filer (inklusive CI-workflows under .gitea/workflows), branches og pull requests
write:user	Oprettelse af et repository for brugeren ved eksport (Gitea kræver det ved POST /user/repos)
write:organization	Visning af brugerens organisationer og oprettelse af et repository for en af dem ved eksport

Gitea viser disse scopes, når brugeren godkender applikationen, og begrænser tokenet til dem.

Gitea-adgangstokens udløber efter en time ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf fornyer dem med det refresh-token, som Gitea udsteder sammen med dem, også når Gitea opbruger refresh-tokens ved brug (INVALIDATE_REFRESH_TOKENS = true), så brugerne forbliver forbundet, indtil de fjerner forbindelsen eller tilbagekalder applikationen i Gitea.

​

Din Gitea-instans

Sæt GITEA_SYNC_URL til webadressen for din instans, dens ROOT_URL, den adresse du åbner repositories med i browseren. REST API’et udledes af den:

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

Gitea, der udstilles under en understi, fungerer også, f.eks. GITEA_SYNC_URL=https://example.com/gitea. Sæt kun GITEA_SYNC_API_URL, hvis din instans udstiller API’et et andet sted, for eksempel bag en API-gateway.

• Opret OAuth2-applikationen på den instans, du angiver i GITEA_SYNC_URL. En applikation fra en anden instans virker ikke.
• GITEA_SYNC_URL er kun webadressen. Tilføj ikke /api/v1 eller en bruger- eller organisationssti.
• Overleaf committer med Giteas fil-API, som kræver webeditoren: hold [repository.editor] aktiveret (standard).

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

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

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 Gitea. Sæt følgende miljøvariabel: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Det skal være en almindelig HTTP/HTTPS-videresendelsesproxy, og den må ikke bruge 127.0.0.1.

​

Hvem kan forbinde og synkronisere

Ligesom på Overleaf Cloud kan kun projektejeren forbinde et projekt med et Gitea-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 Gitea-repository	Projektejeren
Importere et Gitea-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 Gitea via Gitea-kontoen for den bruger, der synkroniserer, så alle samarbejdspartnere, der synkroniserer, forbinder deres egen Gitea-konto og skal have tilladelse til at pushe til repositoryets standardbranch.
• Samarbejdspartnere med kun læseadgang kan ikke bruge Gitea-synkronisering for projektet.
• Når du fjerner forbindelsen til kontoen i Overleaf, glemmer Overleaf dens token; Gitea har intet API til at tilbagekalde det, så tilbagekald også tilladelsen under Settings → Applications i Gitea, hvis du ønsker det.

​

Sådan fungerer synkronisering med Gitea

• Tilladelser: brugerne skal have tilladelse til at pushe til det forbundne repositorys standardbranch. Når en branchbeskyttelsesregel ikke lader brugeren pushe til den, beder Overleaf dem om at kontakte projektejeren, ligesom ved et repository, de har mistet adgangen til.
• Merging: når et projekt er ændret både i Overleaf og i Gitea, committer Overleaf sine ændringer til en midlertidig branch ved navn overleaf-YYYY-MM-DD-HHMMSS og merger den via en pull request med repositoryets standard-merge-stil, fordi Gitea ikke har noget API til at merge branches uden. Efter mergen sletter Overleaf den midlertidige branch; den mergede pull request forbliver i repositoryet som dokumentation.
• Merge-regler: Overleaf omgår aldrig repositoryets branchbeskyttelse. Når pull requesten har en konflikt eller kræver godkendelser eller beståede statuschecks, forbliver den åben, og Overleaf beder brugeren om at merge den i Gitea og derefter fortsætte synkroniseringen.
• CI-workflows: Overleaf viser ikke dotfiler såsom .gitea/workflows/ og lader dem være, som de er i repositoryet. Commits fra Overleaf starter Gitea Actions ligesom alle andre commits.

​

Q&A

Kan jeg force-pushe til standardbranchen?

Svar: Hold venligst force push til standardbranchen deaktiveret, f.eks. med en branchbeskyttelsesregel. Overleaf kan overtage en omskrevet branch, men Gitea-synkronisering er designet til en standardbranch, hvis historik kun vokser.

Kan jeg omdøbe standardbranchen i et forbundet projekt?

Svar: Nej. Overleaf fortsætter med at synkronisere med den branch, projektet blev forbundet med, så synkroniseringer mislykkes, når den branch omdøbes eller fjernes. 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.

Understøtter Gitea-synkronisering Git LFS?

Svar: Nej. Overleaf-projekter understøtter ikke Git Large File Storage. Filer, der spores af Git LFS, vises i Overleaf som LFS-pointerfiler og ikke med deres indhold. Commit i stedet billeder og PDF’er direkte til repositoryet.

Fungerer det med SHA-256-repositories?

Svar: Endnu ikke. Overleaf sammenligner filer ud fra deres SHA-1-ID’er, så i et repository oprettet med objektformatet SHA-256 omskriver hvert pull alle filer, også uændrede. Intet går tabt, men brug venligst standardformatet SHA-1.

Fungerer det med Forgejo?

Svar: Gitea-synkronisering er udviklet og testet udelukkende mod Gitea.