GitLab

Conecta tu repositorio de GitLab a Mintlify para despliegues automáticos, vistas previas de merge requests y sincronización continua.

Mintlify usa tokens de acceso y webhooks para autenticar y sincronizar cambios entre GitLab y Mintlify.

• Mintlify usa tokens de acceso para extraer información de GitLab.
• GitLab usa webhooks para notificar a Mintlify cuando realizas cambios, lo que habilita implementaciones de vista previa para las merge requests.

​

Configura la conexión

Cuando abras Git Settings por primera vez, un asistente de configuración te guía a través de la conexión de tu repositorio de GitLab.

1. Select GitLab as your provider

   En la página de Git Settings, selecciona Connect to GitLab y haz clic en Continue.

2. Download your content

   Si ya tienes un repositorio de GitLab con tu documentación, puedes omitir la descarga y hacer clic en Continue setup directamente.

   Si tu documentación está alojada en Mintlify, descárgala como un archivo zip.

   • Crea un nuevo repositorio en GitLab.
   • Extrae el contenido del zip.
   • Sube el contenido a tu repositorio.

   Haz clic en Continue setup para continuar.

3. Find your project ID

   En tu proyecto de GitLab, ve a Settings > General y ubica tu Project ID.

   
4. Generate an access token

   Ve a Settings > Access Tokens y selecciona Add new token.

   Configura el token con estos parámetros:

   • Name: Mintlify
   • Role: Maintainer (obligatorio para repos privados)
   • Scopes: api y read_api

   Haz clic en Create project access token y copia el token.

   Si los Project Access Tokens no están disponibles, puedes usar un Personal Access Token en su lugar. Ten en cuenta que los Personal Access Tokens caducan y deben actualizarse.

   
5. Connect your repository

   De vuelta en el asistente de configuración, completa los siguientes campos:

   • GitLab instance URL: Déjalo en blanco para gitlab.com, o ingresa la URL de tu instancia autoalojada (por ejemplo, https://gitlab.your-domain.com). Tu instancia debe ser accesible públicamente para que Mintlify pueda conectarse.
   • Project ID: El ID del proyecto de la configuración de tu proyecto de GitLab.
   • GitLab deployment token: El token de acceso que generaste.
   • Branch: Selecciona la rama desde la cual desplegar tu documentación.

   Haz clic en Connect.

   

​

Actualizar una conexión existente

Para modificar la configuración de tu conexión con GitLab después de la configuración inicial, ve a Git Settings y actualiza tu ID de proyecto, token de acceso, rama o URL de instancia directamente.

​

Volver a validar la configuración de Git

Si tu despliegue muestra un comportamiento inesperado, como opciones de rama faltantes o una configuración desactualizada, puedes forzar a Mintlify a actualizar tu origen de Git.

1. Ir a Git Settings

   Ve a Git Settings en tu Dashboard.

2. Volver a validar la configuración

   Haz clic en la insignia verde Active en la esquina del recuadro de configuración de GitLab para volver a validar tu origen de Git. Un toast de éxito confirma cuando se completa la revalidación, y aparece un toast de error si tu configuración necesita revisión.

​

Crear el webhook

Los webhooks notifican a Mintlify cuando envías cambios, para que las implementaciones se activen automáticamente.

1. Agregar nuevo webhook

   1. En GitLab, ve a Settings > Webhooks.
   2. Haz clic en Add new webhook.

   
2. Configurar la URL y el webhook

   Asigna al webhook el nombre Mintlify.

   En el campo URL, introduce el endpoint https://leaves.mintlify.com/gitlab-webhook.

3. Obtener el webtoken

   En tu Dashboard de Mintlify, haz clic en Show Webtoken. Copia el webtoken.

   
4. Pegar el webtoken

   En GitLab, pega el webtoken desde tu Dashboard de Mintlify en el campo Secret token.

5. Seleccionar eventos

   Selecciona los siguientes eventos para activar el webhook:

   • Push events (All branches)
   • Merge requests events
6. Verificar el webhook

   Deberías ver la siguiente configuración después de configurar el webhook:

   • Name: Mintlify
   • URL: https://leaves.mintlify.com/gitlab-webhook
   • Secret token: el webtoken de tu Dashboard de Mintlify
   • Events: Push events (All branches) y Merge requests events

   Añade el webhook.

   
7. Probar el webhook

   Después de crear el webhook, haz clic en el menú desplegable Test. Haz clic en Push events para enviar un payload de prueba. Si la prueba devuelve Hook executed successfully: HTTP 200, configuraste el webhook correctamente.

   

​

GitLab autoalojado por OAuth

Si ejecutas GitLab en tu propia infraestructura, puedes conectar tu instancia autoalojada con Mintlify mediante OAuth. Esta conexión la usan los workflows y el agente para leer repositorios, escuchar eventos de push y de merge request, y abrir merge requests.

GitLab autoalojado por OAuth está disponible actualmente en planes Enterprise. Contacta a tu representante de Mintlify si no ves la opción en tu Dashboard.

Conectar una instancia autoalojada es un proceso de dos pasos:

1. Registra una aplicación OAuth en tu instancia de GitLab.
2. Guarda las credenciales de la aplicación en tu Dashboard de Mintlify y autoriza la conexión.

​

Registrar una aplicación OAuth en tu instancia de GitLab

Puedes registrar la aplicación OAuth como una aplicación a nivel de instancia (solo administradores) o como una aplicación propiedad de un grupo. Por lo general, una aplicación de grupo es suficiente y no requiere acceso de administrador.

1. Abrir la configuración de aplicaciones

   Inicia sesión en tu instancia de GitLab como administrador o propietario del grupo.

   • A nivel de instancia: ve a Admin Area > Applications y haz clic en Add new application.
   • Propiedad de un grupo: abre tu grupo, ve a Settings > Applications y haz clic en Add new application.
2. Configurar la aplicación

   Usa estos valores:

   • Name: Mintlify
   • Redirect URI: https://leaves.mintlify.com/gitlab-oauth/callback
   • Confidential: activado
   • Scopes: api y read_api

   Guarda la aplicación.

3. Copiar las credenciales

   GitLab muestra el Application ID y el Secret. Copia ambos valores ahora; el secreto solo se muestra una vez.

​

Guardar las credenciales en tu Dashboard de Mintlify

1. Abrir Git Settings

   Ve a Git Settings y busca la tarjeta Self-hosted GitLab en la sección de GitLab OAuth.

2. Ingresar los detalles de tu instancia

   Haz clic en Connect Self-Hosted GitLab y completa:

   • GitLab instance URL: la URL base de tu instancia (por ejemplo, https://gitlab.your-company.com). Debe comenzar con https:// o http://.
   • OAuth application client ID: el Application ID del paso anterior.
   • OAuth application client secret: el Secret del paso anterior. Se cifra en reposo y nunca se devuelve por la API después de guardarlo.

   Haz clic en Save instance.

3. Autorizar la conexión

   Haz clic en Authorize self-hosted GitLab. Serás redirigido a tu instancia de GitLab para aprobar los scopes de OAuth y luego volverás al Dashboard.

   Después de autorizar, expande la nueva conexión para explorar los grupos y habilitar proyectos individuales.

​

Administrar la conexión

• Agregar varios usuarios: cada miembro de tu organización puede autorizar su propia cuenta de GitLab contra la misma instancia autoalojada. Haz clic en Add another GitLab connection para agregar más usuarios.
• Rotar credenciales: para rotar el client secret, elimina la instancia guardada y agrégala de nuevo con el nuevo valor. Primero debes revocar cualquier conexión OAuth activa.
• Eliminar la instancia: haz clic en Remove instance en la tarjeta Self-hosted GitLab. Los webhooks existentes para los proyectos conectados se eliminan.

​

Requisitos

• La instancia de GitLab debe ser accesible desde leaves.mintlify.com. Mintlify no puede conectarse a instancias detrás de una VPN o lista de IP permitidas que bloquee nuestro tráfico de salida.
• Necesitas al menos el rol de Maintainer en cada proyecto de GitLab que quieras conectar, para que Mintlify pueda instalar webhooks.
• Solo se puede configurar una instancia autoalojada por organización de Mintlify.