Sincronización con Gitea

Esta función ha sido desarrollada por ayaka-notes/ayakaleaf-pro. Se introduce en la v6.3.2 como versión preliminar y se publicará oficialmente en la v6.4.0, por lo que su configuración y su comportamiento aún pueden cambiar. Necesitamos tus comentarios si tienes algún problema.

La sincronización con Gitea funciona igual que la sincronización con GitHub y la sincronización con GitLab: los usuarios vinculan su cuenta de Gitea, exportan proyectos a nuevos repositorios de Gitea, importan repositorios de Gitea y sincronizan los cambios en ambas direcciones. Funciona con Gitea 1.23 o posterior, en gitea.com o en tu propia instancia.

​

Configurar la sincronización con Gitea

Debes habilitar primero git-bridge antes de usar la sincronización con Gitea.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crea una aplicación OAuth2 en tu instancia de Gitea, en Settings → Applications → Manage OAuth2 applications (o en Site Administration → Integrations → Applications para una aplicación de toda la instancia):

• Application name: p. ej., Overleaf; los usuarios lo ven cuando la autorizan
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: marcado

Copia el Client ID y el Client Secret y, a continuación, añade los siguientes ajustes a tus archivos de variables de entorno de Overleaf.

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

Antes de configurar la URI de redirección de Gitea, asegúrate de que OVERLEAF_SITE_URL esté configurada correctamente.

Overleaf solicita todo lo que necesita una sincronización cuando el usuario vincula la cuenta, de modo que los usuarios nunca tienen que volver a vincularla por falta de un permiso:

Ámbito	Se usa para
write:repository	Repositorios, sus archivos (incluidos los flujos de trabajo de CI en .gitea/workflows), ramas y pull requests
write:user	Crear un repositorio del usuario al exportar (Gitea lo exige en POST /user/repos)
write:organization	Listar las organizaciones del usuario y crear un repositorio de una de ellas al exportar

Gitea muestra estos ámbitos cuando el usuario autoriza la aplicación y limita el token a ellos.

Los tokens de acceso de Gitea caducan al cabo de una hora ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf los renueva con el token de actualización que Gitea emite junto con ellos, también cuando Gitea consume los tokens de actualización al usarlos (INVALIDATE_REFRESH_TOKENS = true), por lo que los usuarios permanecen vinculados hasta que desvinculan o revocan la aplicación en Gitea.

​

Tu instancia de Gitea

Establece GITEA_SYNC_URL en la dirección web de tu instancia, su ROOT_URL, la que usas para abrir repositorios en el navegador. La API REST se deriva de ella:

Variable	Valor predeterminado
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Gitea servido bajo una subruta también funciona, p. ej., GITEA_SYNC_URL=https://example.com/gitea. Establece GITEA_SYNC_API_URL solo cuando tu instancia sirva la API en otro lugar, por ejemplo detrás de un API gateway.

• Crea la aplicación OAuth2 en la instancia que configuraste en GITEA_SYNC_URL; una aplicación de otra instancia no funciona.
• GITEA_SYNC_URL es solo la dirección web. No añadas /api/v1 ni la ruta de un usuario o de una organización.
• Overleaf hace commits con la API de archivos de Gitea, que necesita el editor web: mantén [repository.editor] habilitado (el valor predeterminado).

Si tu instancia usa un certificado de una CA privada, monta el certificado de la CA en el contenedor y apunta NODE_EXTRA_CA_CERTS a él, por ejemplo NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem.

Las cuentas y los proyectos vinculados pertenecen a la instancia con la que se vincularon. Antes de cambiar GITEA_SYNC_URL a otra instancia, pide a los usuarios que desvinculen su cuenta y sus proyectos de Gitea.

Si te encuentras en una región con acceso a la red restringido, es posible que necesites configurar un proxy para acceder a Gitea. Establece la siguiente variable de entorno: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Debe ser un proxy de reenvío HTTP/HTTPS estándar y no debe usar 127.0.0.1.

​

Quién puede vincular y sincronizar

Al igual que en Overleaf Cloud, solo el propietario del proyecto puede vincular un proyecto a un repositorio de Gitea. Una vez vinculado, cualquier colaborador con permiso de edición puede sincronizarlo.

Acción	Quién puede hacerlo
Exportar un proyecto a un nuevo repositorio de Gitea	El propietario del proyecto
Importar un repositorio de Gitea a un nuevo proyecto	Cualquier usuario, que pasa a ser el propietario del nuevo proyecto
Hacer pull, push y merge de un proyecto vinculado	El propietario y los colaboradores con permiso de edición
Desvincular un proyecto de su repositorio	El propietario del proyecto

• Overleaf se comunica con Gitea mediante la cuenta de Gitea del usuario que sincroniza, por lo que cada colaborador que sincroniza vincula su propia cuenta de Gitea y necesita tener permiso para hacer push a la rama predeterminada del repositorio.
• Los colaboradores con permiso de solo lectura no pueden usar la sincronización con Gitea en el proyecto.
• Al desvincular la cuenta en Overleaf se olvida su token; Gitea no tiene ninguna API para revocarlo, así que, si lo deseas, revoca también la autorización en Settings → Applications en Gitea.

​

Cómo funciona la sincronización con Gitea

• Permisos: los usuarios necesitan tener permiso para hacer push a la rama predeterminada del repositorio vinculado. Cuando una regla de protección de rama no permite al usuario hacer push a ella, Overleaf le pide que contacte con el propietario del proyecto, como ocurre con un repositorio al que ha perdido el acceso.
• Fusión: cuando un proyecto ha cambiado tanto en Overleaf como en Gitea, Overleaf hace commit de sus cambios en una rama temporal llamada overleaf-YYYY-MM-DD-HHMMSS y la fusiona mediante una pull request con el estilo de fusión predeterminado del repositorio, porque Gitea no tiene ninguna API para fusionar ramas sin ella. Tras la fusión, Overleaf elimina la rama temporal; la pull request fusionada permanece en el repositorio como registro.
• Reglas de fusión: Overleaf nunca omite la protección de ramas del repositorio. Cuando la pull request tiene un conflicto, o necesita aprobaciones o comprobaciones de estado superadas, permanece abierta y Overleaf pide al usuario que la fusione en Gitea y que después continúe la sincronización.
• Flujos de trabajo de CI: Overleaf no muestra archivos ocultos como .gitea/workflows/ y los deja tal como están en el repositorio. Los commits de Overleaf inician Gitea Actions como cualquier otro commit.

​

Q&A

¿Puedo hacer force push a la rama predeterminada?

Respuesta: Mantén desactivados los force push a la rama predeterminada, p. ej., con una regla de protección de rama. Overleaf puede hacerse cargo de una rama reescrita, pero la sincronización con Gitea está diseñada para una rama predeterminada cuyo historial solo crece.

¿Puedo renombrar la rama predeterminada de un proyecto vinculado?

Respuesta: No. Overleaf sigue sincronizando con la rama a la que se vinculó el proyecto, por lo que las sincronizaciones fallan en cuanto esa rama se renombra o se elimina. Para sincronizar con otra rama, desvincula el proyecto y, a continuación, importa el repositorio a un nuevo proyecto, que usará la rama predeterminada actual.

¿La sincronización con Gitea admite Git LFS?

Respuesta: No. Los proyectos de Overleaf no admiten Git Large File Storage. Los archivos gestionados por Git LFS aparecen en Overleaf como archivos puntero de LFS, no con su contenido. En su lugar, haz commit de las imágenes y los PDF directamente en el repositorio.

¿Funciona con repositorios SHA-256?

Respuesta: Todavía no. Overleaf compara los archivos por sus ID SHA-1, por lo que en un repositorio creado con el formato de objetos SHA-256 cada pull reescribe todos los archivos, incluso los que no han cambiado. No se pierde nada, pero usa el formato SHA-1 predeterminado.

¿Funciona con Forgejo?

Respuesta: La sincronización con Gitea se ha desarrollado y probado únicamente con Gitea.