Sincronización con GitHub

Permite que los usuarios sincronicen sus proyectos con repositorios de GitHub o GitHub Enterprise.

Esta función ha sido desarrollada por ayaka-notes/ayakaleaf-pro y modificada por yu-i-i/overleaf-cep. Está disponible a partir de la v6.2.0. Todavía está en fase beta. Necesitamos tus comentarios si tienes algún problema.

​

Configurar la sincronización con GitHub

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Visita la configuración para desarrolladores para crear tu aplicación OAuth de GitHub y copia tu CLIENT_ID y tu SECRET.

Nota: cuando crees la OAuth App, introduce ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback en Authorization callback URL. Ayakaleaf Pro construye la misma dirección a partir de OVERLEAF_SITE_URL, así que no hay que configurar nada para ella en config/variables.env.

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 GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

Antes de configurar la URL de callback de OAuth de GitHub, asegúrate de que OVERLEAF_SITE_URL esté configurada correctamente.

Si te encuentras en una región con acceso a la red restringido, es posible que necesites configurar un proxy para acceder a GitHub. Establece la siguiente variable de entorno: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Asegúrate de que el uso de un proxy cumpla con las leyes y normativas locales.

GITHUB_SYNC_PROXY_URL debe ser un proxy de reenvío HTTP/HTTPS estándar (por ejemplo, el puerto HTTP de Clash). No se admiten mirrors de descarga de GitHub como gh-proxy.org.

No uses 127.0.0.1 como host del proxy. Si el proxy se ejecuta en el servidor host, usa la dirección IP de la LAN del servidor (como 192.168.1.xx) y asegúrate de que el proxy esté configurado para aceptar conexiones de dispositivos de la red local.

​

GitHub Enterprise

La compatibilidad con GitHub Enterprise está disponible a partir de la v6.3.1. Las versiones anteriores solo se conectan a github.com, y las variables siguientes no tienen ningún efecto.

De forma predeterminada, la sincronización con GitHub se conecta a github.com. Para usar GitHub Enterprise Server (autoalojado) o GitHub Enterprise Cloud con residencia de datos (GHE.com), establece GITHUB_SYNC_URL en la dirección web de tu instancia, la que usas para abrir repositorios en el navegador.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Los endpoints de las API REST y GraphQL se derivan de GITHUB_SYNC_URL de la misma forma que lo hace GitHub CLI:

GITHUB_SYNC_URL	API REST	API GraphQL
https://github.com (predeterminado)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (cualquier otro)	https://HOST/api/v3	https://HOST/api/graphql

Establece los endpoints de la API solo cuando tu instancia los sirva en otro lugar, por ejemplo detrás de un API gateway:

Variable	Valor predeterminado
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Derivado de GITHUB_SYNC_URL; consulta la tabla anterior
GITHUB_SYNC_GRAPHQL_URL	Derivado de GITHUB_SYNC_API_URL cuando está establecido (/api/v3 pasa a ser /api/graphql; en caso contrario, se añade /graphql); si no, de GITHUB_SYNC_URL

• Crea la aplicación OAuth en tu instancia empresarial (Settings → Developer settings → OAuth Apps); una aplicación de github.com no funciona allí. La URL de callback es la misma: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL es solo la dirección web. No la establezcas en una dirección de API como https://api.github.com o https://HOST/api/v3, y no añadas la ruta de una organización.
• Las tres direcciones deben apuntar a la misma instancia de GitHub.

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

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

​

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 GitHub. 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 GitHub	El propietario del proyecto
Importar un repositorio de GitHub 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 GitHub mediante la cuenta de GitHub del usuario que sincroniza, por lo que cada colaborador que sincroniza vincula su propia cuenta de GitHub 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 GitHub en el proyecto.

​

Q&A

¿Cómo vinculo un proyecto a GitHub y lo sincronizo?

Respuesta: En el editor, abre Integrations y haz clic en GitHub. Si tu cuenta de GitHub aún no está vinculada, haz clic primero en Link to your GitHub account. En Export Project to GitHub, introduce un nombre de repositorio, elige Private en Repository visibility y haz clic en Create a GitHub repository.

A partir de entonces, la misma tarjeta abre Sync with GitHub, que muestra los nuevos commits en GitHub. Haz clic en Sync para hacer commit de tus cambios de Overleaf en la rama predeterminada e incorporar los cambios de GitHub al proyecto. La sincronización funciona en ambas direcciones, pero solo se ejecuta cuando alguien hace clic en Sync; no hay sincronización programada. Cuando ambos lados han cambiado, Overleaf fusiona a través de una rama temporal llamada overleaf-YYYY-MM-DD-HHMMSS. Si esa fusión tiene un conflicto, fusiona tú mismo la rama en GitHub y, a continuación, haz clic en I have manually merged. Continue.

¿Puedo hacer force push a la rama predeterminada?

Respuesta: No lo recomendamos. Overleaf detecta un force push, avisa de ello y se hace cargo de la rama reescrita, fusionando los cambios realizados en Overleaf desde la última sincronización. Para evitar sorpresas, protege la rama predeterminada frente a force push en la configuración del repositorio.

¿Puedo renombrar la rama predeterminada de un proyecto vinculado?

Respuesta: Por favor, no lo hagas. Overleaf sigue sincronizando con la rama a la que se vinculó el proyecto. 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 GitHub muestra «Something wrong with GitHub request»

Respuesta: Este mensaje significa que el servidor no pudo llegar a GitHub, por ejemplo por un problema de red, DNS, TLS o proxy. Ejecuta bin/logs web para ver el error completo. Si el servidor necesita un proxy para llegar a GitHub, establece GITHUB_SYNC_PROXY_URL.

¿Debo desactivar «Expire user access tokens» en la GitHub OAuth App?

Respuesta: Sí. La sincronización con GitHub no renueva los tokens caducados. Con los tokens con caducidad habilitados, los usuarios tienen que volver a conectar GitHub cada vez que caduca su token.

¿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 GitHub; si para ello necesita un proxy, establece GITHUB_SYNC_PROXY_URL. GitHub nunca llama a tu instancia: un proyecto solo se sincroniza cuando un usuario lo sincroniza en el editor.

La vinculación de mi cuenta de GitHub falla o me devuelve sin vincularla

Respuesta: Comprueba lo siguiente, por orden:

• Abre Overleaf en la dirección exacta establecida en OVERLEAF_SITE_URL. GitHub te devuelve a ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, y tu sesión solo existe en la dirección desde la que empezaste, así que otro host, IP o puerto termina en la página de inicio de sesión o en “Restricted, sorry you don’t have permission to load this page”.
• La Authorization callback URL de la OAuth App debe ser ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, con el mismo esquema, host y puerto.
• Una página de error con Failed to obtain access token from Git server significa que GitHub no devolvió un token: comprueba GITHUB_SYNC_CLIENT_ID y GITHUB_SYNC_CLIENT_SECRET, y que el servidor pueda llegar a GitHub. Ejecuta bin/logs web para ver el error completo.

Después de modificar config/variables.env, ejecuta bin/up para volver a crear los contenedores.

La importación de un repositorio falla con «EmptyZipFileError: empty_zip_file» o «unzip failed»

Respuesta: Overleaf importa el archivo zip del último commit de la rama predeterminada del repositorio, y este error significa que ese archivo no contiene ningún archivo que Overleaf pueda importar. Comprueba la rama predeterminada en GitHub:

• Contiene los archivos del proyecto, no solo archivos que Overleaf omite al importar: archivos ocultos como .gitignore y .gitmodules (.latexmkrc se conserva) y archivos de compilación como *.aux, *.log, *.bbl, *.synctex.gz, *.doc y *.docx.
• Los archivos no están únicamente dentro de submódulos de Git. El archivo comprimido de GitHub deja los submódulos como carpetas vacías.
• Los archivos que esperas están en la rama predeterminada, no en otra rama. La importación siempre usa la rama predeterminada.

La importación de un repositorio falla con «connect ECONNREFUSED» a «sharelatex:3054»

Respuesta: V1_HISTORY_URL está establecida en http://sharelatex:3054, un valor que indicaban versiones anteriores de esta documentación. El puerto 3054 corresponde al servicio project-history, que solo escucha dentro del contenedor, mientras que V1_HISTORY_URL debe apuntar a history-v1. Overleaf guarda en history-v1 todos los archivos binarios (imágenes, PDF) del repositorio importado, por lo que la importación falla; subir un archivo de ese tipo en el editor falla de la misma forma. En tu docker-compose.yml, establece V1_HISTORY_URL: "http://sharelatex:3100/api" en el servicio sharelatex (consulta Integración con Git) y vuelve a crear el contenedor. El Toolkit ya establece este valor; comprueba que docker-compose.override.yml no lo sobrescriba.