Sincronización con GitLab

Permite a los usuarios sincronizar sus proyectos con repositorios en GitLab.com o en un GitLab autogestionado.

Esta función ha sido desarrollada por ayaka-notes/ayakaleaf-pro. Se introduce en la v6.3.1 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 GitLab funciona igual que la sincronización con GitHub: los usuarios vinculan su cuenta de GitLab, exportan proyectos a nuevos proyectos de GitLab, importan repositorios de GitLab y sincronizan los cambios en ambas direcciones. Funciona con GitLab.com y con GitLab autogestionado 15.10 o posterior (Community y Enterprise Edition).

​

Configurar la sincronización con GitLab

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Crea una aplicación OAuth en tu instancia de GitLab, en User settings → Applications (o en Admin area → Applications para una aplicación de toda la instancia):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: marcado
• Scopes: api

Copia el Application ID y el 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 GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

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

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

Los tokens de acceso de GitLab caducan a las dos horas. Overleaf los renueva con el token de actualización que GitLab emite junto con ellos, por lo que los usuarios permanecen vinculados hasta que desvinculan o revocan la aplicación en GitLab.

​

GitLab autogestionado

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

Variable	Valor predeterminado
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Establece GITLAB_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 OAuth en la instancia que configuraste en GITLAB_SYNC_URL; una aplicación de gitlab.com no funciona en una instancia autogestionada.
• GITLAB_SYNC_URL es solo la dirección web. No añadas /api/v4 ni la ruta de un grupo.

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

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

Si te encuentras en una región con acceso a la red restringido, es posible que necesites configurar un proxy para acceder a GitLab. Establece la siguiente variable de entorno: GITLAB_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 GitLab. 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 GitLab	El propietario del proyecto
Importar un repositorio de GitLab 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 GitLab mediante la cuenta de GitLab del usuario que sincroniza, por lo que cada colaborador que sincroniza vincula su propia cuenta de GitLab 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 GitLab en el proyecto.

​

Cómo funciona la sincronización con GitLab

• Permisos: los usuarios necesitan tener permiso para hacer push a la rama predeterminada del proyecto vinculado. Cuando la rama predeterminada está protegida y el usuario no puede 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 GitLab, Overleaf hace commit de sus cambios en una rama temporal llamada overleaf-YYYY-MM-DD-HHMMSS y la fusiona mediante una merge request, porque GitLab no tiene ninguna API para fusionar ramas sin ella. Tras la fusión, Overleaf elimina la rama temporal y la merge request. En GitLab solo los administradores y los propietarios del proyecto pueden eliminar merge requests, por lo que para los demás usuarios la merge request fusionada permanece en el proyecto.
• Reglas de fusión: Overleaf nunca omite las reglas de fusión del proyecto. Cuando la merge request tiene un conflicto, o necesita una aprobación o un pipeline superado, permanece abierta y Overleaf pide al usuario que la fusione en GitLab y que después continúe la sincronización.
• Pipelines: los commits de Overleaf inician pipelines como cualquier otro commit. Si tu proyecto ejecuta pipelines para merge requests y exige que se superen, las fusiones desde Overleaf esperan a que terminen, como se describe más arriba.

​

Q&A

¿Puedo hacer force push a la rama predeterminada?

Respuesta: Mantén desactivados los force push a la rama predeterminada. Este es el comportamiento predeterminado de GitLab: la rama predeterminada de un proyecto nuevo está protegida y nadie puede hacer force push a ella. Overleaf puede hacerse cargo de una rama reescrita, pero la sincronización con GitLab 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 GitLab 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 versiones anteriores a GitLab 17.9, al importar un repositorio se incorpora su contenido, que la primera sincronización sustituye por los archivos puntero. En su lugar, haz commit de las imágenes y los PDF directamente en el repositorio.

¿Mi instancia tiene que ser accesible desde internet?

Respuesta: No. La vinculación de una cuenta pasa por el navegador del usuario, así que la dirección de callback de OAuth solo tiene que abrirse en el navegador del usuario. El servidor solo necesita llegar a GitLab; si para ello necesita un proxy, establece GITLAB_SYNC_PROXY_URL. GitLab nunca llama a tu instancia: un proyecto solo se sincroniza cuando un usuario lo sincroniza en el editor.