> ## Documentation Index
> Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth de GitLab autoalojado

> Conecta una instancia autoalojada de GitLab con Mintlify mediante OAuth para clonar repositorios, enviar commits y abrir merge requests automatizados.

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](/es/automations).

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.

<Note>
  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](/es/deploy/gitlab). La integración de OAuth depende de la conexión del lado del despliegue.
</Note>

<div id="prerequisites">
  ## Requisitos previos
</div>

* 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](https://app.mintlify.com/settings/deployment/git-settings).

<div id="set-up-the-connection">
  ## Configura la conexión
</div>

<Steps>
  <Step title="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**.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>
</Steps>

<div id="rotate-credentials">
  ## Rotar credenciales
</div>

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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Remove the instance">
    En la tarjeta **Self-hosted GitLab**, haz clic en **Remove instance**.
  </Step>

  <Step title="Re-add with new credentials">
    Sigue los pasos de **Set up the connection** descritos anteriormente con el nuevo client secret.
  </Step>
</Steps>

<div id="troubleshooting">
  ## Resolución de problemas
</div>

<div id="invalid_client-after-authorizing">
  ### `invalid_client` después de autorizar
</div>

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](#rotate-credentials) con el secreto actual.

<div id="webhook-registration-failed-invalid-url-given">
  ### El registro del webhook falló: `Invalid url given`
</div>

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.

<div id="no-consent-screen-on-authorize">
  ### No aparece pantalla de consentimiento al autorizar
</div>

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.