Saltar al contenido principal
Mintlify admite la autorización basada en OAuth para instancias autoalojadas de GitLab, además de gitlab.com. OAuth permite que el agente de Mintlify actúe como un usuario de GitLab durante las ejecuciones de automatización: clonar repositorios, enviar commits, abrir merge requests y registrar webhooks de proyectos. Debes configurar la autorización OAuth para las instancias autoalojadas de GitLab a fin de habilitar automatizaciones. A diferencia de gitlab.com, donde Mintlify proporciona una única aplicación OAuth contra la que se autoriza cada cliente, cada instancia autoalojada debe registrar su propia aplicación OAuth. Crea la aplicación en tu instancia de GitLab, comparte sus credenciales con Mintlify y, a continuación, completa una autorización OAuth para conectar un usuario.
Esta guía abarca únicamente la integración OAuth que impulsa las automatizaciones. Debes configurar por separado la conexión del lado del despliegue (utilizada para la sincronización de contenido y las vistas previas) con un deploy token; consulta la guía de GitLab. La integración de OAuth depende de la conexión del lado del despliegue.

​
Requisitos previos

  • Acceso de administrador a tu instancia autoalojada de GitLab.
  • Tu instancia de GitLab debe ser accesible desde https://app.mintlify.com. Las instancias detrás de una VPN o de un firewall que bloquee la entrada pública no funcionan.
  • Una organización de Mintlify que tenga habilitada la función de GitLab autoalojado. Contacta con soporte si no ves la sección Self-hosted GitLab en la página del dashboard Git settings.

​
Configura la conexión

1

Register an OAuth application on your GitLab instance

En tu GitLab autoalojado, inicia sesión como administrador y ve a Admin Area > Applications > Add new application.Configura la aplicación con estos valores:
  • Name: Mintlify
  • Redirect URI: https://app.mintlify.com/api/gitlab-oauth/callback
  • Trusted: déjalo sin marcar. Marcar la aplicación como confiable omite la pantalla de consentimiento para todos los usuarios; dejarlo sin marcar muestra un mensaje de autorización normal la primera vez que cada usuario se conecta.
  • Confidential: marcado. Mintlify es un cliente del lado del servidor y mantiene el secreto confidencial.
  • Scopes: selecciona api, read_repository y write_repository. El agente los usa para leer metadatos de proyectos, clonar repositorios y enviar commits.
Haz clic en Save application.
Editar una aplicación OAuth en GitLab puede rotar el client secret de manera silenciosa. Si haces cambios más adelante, haz clic en Renew secret y actualiza el nuevo valor en Mintlify.
2

Copy the application credentials

Después de guardar, GitLab muestra el Application ID y el Secret de la aplicación. Mantén esta página abierta: el secreto solo se muestra una vez.
3

Register the instance in Mintlify

En tu dashboard de Mintlify, abre Settings > Git settings y busca la sección Self-hosted GitLab dentro de GitLab OAuth.Haz clic en Connect Self-Hosted GitLab e introduce:
  • GitLab instance URL: la URL pública de tu instancia de GitLab, por ejemplo https://gitlab.your-company.com. Mintlify se comunica con tu instancia a través de esta URL al intercambiar tokens y llamar a la API de GitLab.
  • OAuth application client ID: el Application ID del paso anterior.
  • OAuth application client secret: el Secret del paso anterior.
Haz clic en Save instance. Mintlify cifra el secreto en reposo y nunca lo devuelve al navegador después de guardarlo.
4

Authorize

Haz clic en Authorize self-hosted GitLab. Serás redirigido a tu instancia de GitLab, se te pedirá que inicies sesión si es necesario y verás una pantalla de consentimiento con los scopes solicitados.Después de hacer clic en Authorize en GitLab, volverás a Mintlify y la nueva conexión aparecerá en la lista de instalaciones, con una insignia que muestra el nombre de host de tu instancia.
5

Choose projects

Expande la conexión en el dashboard. Mintlify lista todos los grupos a los que el usuario que autoriza tiene acceso como Maintainer o superior, además de una entrada Personal projects para los proyectos en el namespace personal del usuario.Marca la casilla junto a cada proyecto que deba participar en las automatizaciones. Mintlify registra un webhook en el proyecto, genera un secret token y lo almacena cifrado. A partir de ese momento, Mintlify recibe eventos de push y merge-request de tu instancia para ese proyecto.
El usuario que se conecta debe tener el rol Maintainer en un proyecto para que Mintlify pueda emitir project access tokens de corta duración durante las ejecuciones de automatización. Sin Maintainer, el agente puede leer pero no puede enviar commits ni abrir merge requests.

​
Rotar credenciales

Si necesitas cambiar el client secret de la aplicación registrada —por ejemplo, después de renovarlo en GitLab—, elimina la instancia guardada en Mintlify y vuelve a añadirla con los nuevos valores. Primero debes revocar las conexiones OAuth activas; de lo contrario, Mintlify bloqueará la eliminación.
1

Revoke each connection

Haz clic en Revoke en cada instalación listada bajo la instancia autoalojada. Esto elimina el webhook en cada proyecto conectado y revoca el token OAuth en GitLab.
2

Remove the instance

En la tarjeta Self-hosted GitLab, haz clic en Remove instance.
3

Re-add with new credentials

Sigue los pasos de Set up the connection descritos anteriormente con el nuevo client secret.

​
Resolución de problemas

​
invalid_client después de autorizar

GitLab rechazó el paso de intercambio de tokens porque el client secret que envió Mintlify no coincide con el registrado en la aplicación. La causa más habitual es que el secreto se rotó en GitLab —por una acción explícita de Renew secret, o de forma silenciosa cuando alguien editó la aplicación— y el valor en Mintlify está obsoleto. Solución: rota las credenciales siguiendo los pasos de Rotar credenciales con el secreto actual.

​
El registro del webhook falló: Invalid url given

GitLab se negó a registrar el webhook porque la URL que envió Mintlify (https://app.mintlify.com/gitlab-oauth-webhook) fue rechazada por la lista de permitidos de solicitudes salientes de GitLab. Las instancias autoalojadas rechazan las URLs “locales” a menos que el administrador las permita explícitamente. Solución: en el área de administración de GitLab, ve a Settings > Network > Outbound requests y activa Allow requests to the local network from webhooks and integrations. Si tu política de red bloquea app.mintlify.com, contacta con tu administrador de red para permitir HTTPS saliente hacia ese host. Si no ves el cuadro de diálogo de consentimiento de GitLab al autorizar, puede deberse a una de estas causas:
  • La aplicación está marcada como Trusted en GitLab. Las aplicaciones marcadas como confiables omiten el consentimiento para todos los usuarios. Desmarca Trusted en la configuración de la aplicación si quieres que los usuarios vean y confirmen los scopes.
  • Tu usuario de GitLab ha autorizado previamente la aplicación con los mismos scopes. GitLab recuerda las concesiones anteriores y omite el consentimiento en autorizaciones posteriores. Revoca la autorización de la aplicación en User settings > Applications > Authorized applications para volver a ver el consentimiento.

Temas relacionados

Actualizaciones de productoFlujos de trabajoGitLab