From 3fa7caf4adfa6a89f4074a1ef4f8f9d1adff8634 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 8 May 2026 00:13:37 +0000 Subject: [PATCH] Add self-hosted GitLab OAuth setup guide Generated-By: mintlify-agent --- deploy/gitlab-self-hosted.mdx | 84 ++++++++++++++++++++++++++++++++ docs.json | 3 +- es.json | 3 +- es/deploy/gitlab-self-hosted.mdx | 84 ++++++++++++++++++++++++++++++++ fr.json | 3 +- fr/deploy/gitlab-self-hosted.mdx | 84 ++++++++++++++++++++++++++++++++ zh.json | 3 +- zh/deploy/gitlab-self-hosted.mdx | 84 ++++++++++++++++++++++++++++++++ 8 files changed, 344 insertions(+), 4 deletions(-) create mode 100644 deploy/gitlab-self-hosted.mdx create mode 100644 es/deploy/gitlab-self-hosted.mdx create mode 100644 fr/deploy/gitlab-self-hosted.mdx create mode 100644 zh/deploy/gitlab-self-hosted.mdx diff --git a/deploy/gitlab-self-hosted.mdx b/deploy/gitlab-self-hosted.mdx new file mode 100644 index 000000000..82dc1eba6 --- /dev/null +++ b/deploy/gitlab-self-hosted.mdx @@ -0,0 +1,84 @@ +--- +title: "Self-hosted GitLab" +description: "Connect a GitLab instance you run yourself to Mintlify by registering an OAuth application and configuring the connection in your dashboard." +keywords: ["self-hosted GitLab", "GitLab OAuth", "GitLab Enterprise", "OAuth application"] +--- + +This guide walks you through connecting a self-hosted GitLab instance to Mintlify. You register an OAuth application on your GitLab instance, then provide its client ID and secret in your Mintlify dashboard so workflows can authorize against your instance. + +If you use GitLab.com, see the [GitLab](/deploy/gitlab) page for setup instructions. + +## Prerequisites + +- Admin or maintainer access to your GitLab instance to register an OAuth application +- A publicly accessible URL for your GitLab instance so Mintlify can reach it +- Access to your Mintlify dashboard with the `Self-hosted GitLab OAuth` feature enabled for your organization + +## Step 1: Register the OAuth application on your GitLab instance + +Register a new OAuth application on your GitLab instance. You can do this at the instance, group, or user level depending on how you want to scope access. + + + + On your GitLab instance, go to **Admin Area** > **Applications** to register an instance-wide application, or **User Settings** > **Applications** to register one under your user account. + + + Set the following fields: + + - **Name**: `Mintlify` + - **Redirect URI**: `https://leaves.mintlify.com/gitlab-oauth-webhook` + - **Confidential**: Enabled + - **Scopes**: `api`, `read_repository`, `write_repository` + + + The `api` scope is required so Mintlify can read project metadata and create webhooks. The `read_repository` and `write_repository` scopes allow Mintlify to clone your documentation and push preview deployments. + + + + Save the application. GitLab displays the **Application ID** (client ID) and **Secret** (client secret). Record both before leaving the page; the secret is only shown once. + + + +## Step 2: Connect your instance in the Mintlify dashboard + + + + In your [Mintlify dashboard](https://dashboard.mintlify.com), go to **Settings** > **Git settings** > **GitLab OAuth**, then locate the **Self-hosted GitLab** section. + + + Click **Connect Self-Hosted GitLab** and fill in the following fields: + + - **GitLab instance URL**: The base URL of your instance, for example `https://gitlab.your-company.com`. + - **OAuth application client ID**: The Application ID from Step 1. + - **OAuth application client secret**: The Secret from Step 1. + + Click **Save instance**. Your client secret is encrypted at rest and is never returned by the API after saving. + + + Click **Authorize self-hosted GitLab**. You are redirected to your instance to approve the OAuth application, then sent back to the dashboard. + + + Expand a group in the installations list and select the projects you want to connect. Mintlify enables webhooks on each selected project so deployments trigger automatically when you push changes. + + + +## Rotate or remove credentials + +To rotate your OAuth credentials, remove the existing instance from the **Self-hosted GitLab** section and add it again with the new client ID and secret. Removing an instance also revokes any active installations connected through it. + +## Troubleshooting + + + + Self-hosted GitLab OAuth is gated behind an organization feature flag. Contact your customer success representative or [support@mintlify.com](mailto:support@mintlify.com) to enable it for your organization. + + + The redirect URI registered on your OAuth application must exactly match `https://leaves.mintlify.com/gitlab-oauth-webhook`. Update your application on GitLab and try again. + + + Your instance must be reachable from the public internet. Verify your firewall allows inbound HTTPS connections from Mintlify and that your instance has a valid SSL certificate. + + + The user who authorized the OAuth application must have at least the **Maintainer** role on each connected project. Reauthorize with a user that has the required role, or upgrade the role on the affected projects. + + diff --git a/docs.json b/docs.json index 997df9ddb..80259317b 100644 --- a/docs.json +++ b/docs.json @@ -209,7 +209,8 @@ "deploy/ci", "deploy/github", "deploy/ghes", - "deploy/gitlab" + "deploy/gitlab", + "deploy/gitlab-self-hosted" ] }, { diff --git a/es.json b/es.json index d55123c24..3f1080bb7 100644 --- a/es.json +++ b/es.json @@ -177,7 +177,8 @@ "es/deploy/ci", "es/deploy/github", "es/deploy/ghes", - "es/deploy/gitlab" + "es/deploy/gitlab", + "es/deploy/gitlab-self-hosted" ] }, { diff --git a/es/deploy/gitlab-self-hosted.mdx b/es/deploy/gitlab-self-hosted.mdx new file mode 100644 index 000000000..1b8e18994 --- /dev/null +++ b/es/deploy/gitlab-self-hosted.mdx @@ -0,0 +1,84 @@ +--- +title: "GitLab autoalojado" +description: "Conecta una instancia de GitLab que administras tú mismo a Mintlify registrando una aplicación OAuth y configurando la conexión en tu panel." +keywords: ["GitLab autoalojado", "GitLab OAuth", "GitLab Enterprise", "aplicación OAuth"] +--- + +Esta guía te muestra cómo conectar una instancia de GitLab autoalojada a Mintlify. Registras una aplicación OAuth en tu instancia de GitLab y luego proporcionas su client ID y secret en tu panel de Mintlify para que los flujos puedan autorizarse contra tu instancia. + +Si usas GitLab.com, consulta la página de [GitLab](/es/deploy/gitlab) para ver las instrucciones de configuración. + +## Requisitos previos + +- Acceso de administrador o mantenedor a tu instancia de GitLab para registrar una aplicación OAuth +- Una URL accesible públicamente para tu instancia de GitLab para que Mintlify pueda alcanzarla +- Acceso a tu panel de Mintlify con la función `Self-hosted GitLab OAuth` habilitada para tu organización + +## Paso 1: Registra la aplicación OAuth en tu instancia de GitLab + +Registra una nueva aplicación OAuth en tu instancia de GitLab. Puedes hacerlo a nivel de instancia, grupo o usuario según cómo quieras delimitar el acceso. + + + + En tu instancia de GitLab, ve a **Área de administración** > **Aplicaciones** para registrar una aplicación a nivel de instancia, o a **Configuración de usuario** > **Aplicaciones** para registrar una bajo tu cuenta de usuario. + + + Establece los siguientes campos: + + - **Nombre**: `Mintlify` + - **URI de redirección**: `https://leaves.mintlify.com/gitlab-oauth-webhook` + - **Confidencial**: Habilitado + - **Ámbitos**: `api`, `read_repository`, `write_repository` + + + El ámbito `api` es necesario para que Mintlify pueda leer los metadatos del proyecto y crear webhooks. Los ámbitos `read_repository` y `write_repository` permiten que Mintlify clone tu documentación e implemente despliegues de vista previa. + + + + Guarda la aplicación. GitLab muestra el **Application ID** (client ID) y el **Secret** (client secret). Registra ambos antes de salir de la página; el secret solo se muestra una vez. + + + +## Paso 2: Conecta tu instancia en el panel de Mintlify + + + + En tu [panel de Mintlify](https://dashboard.mintlify.com), ve a **Configuración** > **Configuración de Git** > **GitLab OAuth** y luego ubica la sección **Self-hosted GitLab**. + + + Haz clic en **Connect Self-Hosted GitLab** y completa los siguientes campos: + + - **GitLab instance URL**: La URL base de tu instancia, por ejemplo `https://gitlab.tu-empresa.com`. + - **OAuth application client ID**: El Application ID del Paso 1. + - **OAuth application client secret**: El Secret del Paso 1. + + Haz clic en **Save instance**. Tu client secret se cifra en reposo y nunca se devuelve por la API después de guardarlo. + + + Haz clic en **Authorize self-hosted GitLab**. Te redirigimos a tu instancia para aprobar la aplicación OAuth y luego te enviamos de vuelta al panel. + + + Expande un grupo en la lista de instalaciones y selecciona los proyectos que quieras conectar. Mintlify habilita los webhooks en cada proyecto seleccionado para que los despliegues se activen automáticamente cuando envíes cambios. + + + +## Rotar o eliminar credenciales + +Para rotar tus credenciales OAuth, elimina la instancia existente de la sección **Self-hosted GitLab** y agrégala de nuevo con el nuevo client ID y secret. Eliminar una instancia también revoca cualquier instalación activa conectada a través de ella. + +## Solución de problemas + + + + GitLab OAuth autoalojado está protegido por una bandera de función a nivel de organización. Contacta a tu representante de éxito del cliente o a [support@mintlify.com](mailto:support@mintlify.com) para habilitarlo en tu organización. + + + La URI de redirección registrada en tu aplicación OAuth debe coincidir exactamente con `https://leaves.mintlify.com/gitlab-oauth-webhook`. Actualiza tu aplicación en GitLab e inténtalo de nuevo. + + + Tu instancia debe ser accesible desde la red pública. Comprueba que tu cortafuegos permita conexiones HTTPS entrantes desde Mintlify y que tu instancia tenga un certificado SSL válido. + + + El usuario que autorizó la aplicación OAuth debe tener al menos el rol **Maintainer** en cada proyecto conectado. Vuelve a autorizar con un usuario que tenga el rol requerido o aumenta el rol en los proyectos afectados. + + diff --git a/fr.json b/fr.json index 871a32d0e..e192283fc 100644 --- a/fr.json +++ b/fr.json @@ -177,7 +177,8 @@ "fr/deploy/ci", "fr/deploy/github", "fr/deploy/ghes", - "fr/deploy/gitlab" + "fr/deploy/gitlab", + "fr/deploy/gitlab-self-hosted" ] }, { diff --git a/fr/deploy/gitlab-self-hosted.mdx b/fr/deploy/gitlab-self-hosted.mdx new file mode 100644 index 000000000..864ffcbe2 --- /dev/null +++ b/fr/deploy/gitlab-self-hosted.mdx @@ -0,0 +1,84 @@ +--- +title: "GitLab auto-hébergé" +description: "Connectez à Mintlify une instance GitLab que vous gérez vous-même en enregistrant une application OAuth et en configurant la connexion dans votre tableau de bord." +keywords: ["GitLab auto-hébergé", "GitLab OAuth", "GitLab Enterprise", "application OAuth"] +--- + +Ce guide vous explique comment connecter une instance GitLab auto-hébergée à Mintlify. Vous enregistrez une application OAuth sur votre instance GitLab, puis vous fournissez son client ID et son secret dans votre tableau de bord Mintlify pour que les workflows puissent s’authentifier auprès de votre instance. + +Si vous utilisez GitLab.com, consultez la page [GitLab](/fr/deploy/gitlab) pour les instructions de configuration. + +## Prérequis + +- Un accès administrateur ou mainteneur à votre instance GitLab pour enregistrer une application OAuth +- Une URL accessible publiquement pour votre instance GitLab afin que Mintlify puisse l’atteindre +- Un accès à votre tableau de bord Mintlify avec la fonctionnalité `Self-hosted GitLab OAuth` activée pour votre organisation + +## Étape 1 : enregistrez l’application OAuth sur votre instance GitLab + +Enregistrez une nouvelle application OAuth sur votre instance GitLab. Vous pouvez le faire au niveau de l’instance, du groupe ou de l’utilisateur selon la portée d’accès souhaitée. + + + + Sur votre instance GitLab, allez dans **Zone d’administration** > **Applications** pour enregistrer une application à l’échelle de l’instance, ou dans **Paramètres utilisateur** > **Applications** pour en enregistrer une sous votre compte utilisateur. + + + Renseignez les champs suivants : + + - **Nom** : `Mintlify` + - **URI de redirection** : `https://leaves.mintlify.com/gitlab-oauth-webhook` + - **Confidentielle** : activée + - **Portées** : `api`, `read_repository`, `write_repository` + + + La portée `api` est requise pour que Mintlify puisse lire les métadonnées du projet et créer des webhooks. Les portées `read_repository` et `write_repository` permettent à Mintlify de cloner votre documentation et de pousser des déploiements d’aperçu. + + + + Enregistrez l’application. GitLab affiche l’**Application ID** (client ID) et le **Secret** (client secret). Notez les deux avant de quitter la page ; le secret n’est affiché qu’une seule fois. + + + +## Étape 2 : connectez votre instance dans le tableau de bord Mintlify + + + + Dans votre [tableau de bord Mintlify](https://dashboard.mintlify.com), allez dans **Paramètres** > **Paramètres Git** > **GitLab OAuth**, puis localisez la section **Self-hosted GitLab**. + + + Cliquez sur **Connect Self-Hosted GitLab** et remplissez les champs suivants : + + - **GitLab instance URL** : l’URL de base de votre instance, par exemple `https://gitlab.votre-entreprise.com`. + - **OAuth application client ID** : l’Application ID de l’étape 1. + - **OAuth application client secret** : le Secret de l’étape 1. + + Cliquez sur **Save instance**. Votre client secret est chiffré au repos et n’est jamais renvoyé par l’API après l’enregistrement. + + + Cliquez sur **Authorize self-hosted GitLab**. Vous êtes redirigé vers votre instance pour approuver l’application OAuth, puis renvoyé vers le tableau de bord. + + + Développez un groupe dans la liste des installations et sélectionnez les projets que vous souhaitez connecter. Mintlify active des webhooks sur chaque projet sélectionné afin que les déploiements se déclenchent automatiquement lorsque vous poussez des modifications. + + + +## Faire tourner ou supprimer les identifiants + +Pour faire tourner vos identifiants OAuth, supprimez l’instance existante de la section **Self-hosted GitLab** et ajoutez-la à nouveau avec les nouveaux client ID et secret. La suppression d’une instance révoque également toutes les installations actives connectées via celle-ci. + +## Dépannage + + + + L’OAuth GitLab auto-hébergé est protégé par un drapeau de fonctionnalité au niveau de l’organisation. Contactez votre représentant Customer Success ou [support@mintlify.com](mailto:support@mintlify.com) pour l’activer pour votre organisation. + + + L’URI de redirection enregistrée sur votre application OAuth doit correspondre exactement à `https://leaves.mintlify.com/gitlab-oauth-webhook`. Mettez à jour votre application sur GitLab et réessayez. + + + Votre instance doit être joignable depuis l’internet public. Vérifiez que votre pare-feu autorise les connexions HTTPS entrantes depuis Mintlify et que votre instance dispose d’un certificat SSL valide. + + + L’utilisateur qui a autorisé l’application OAuth doit avoir au moins le rôle **Maintainer** sur chaque projet connecté. Réautorisez avec un utilisateur disposant du rôle requis, ou augmentez le rôle sur les projets concernés. + + diff --git a/zh.json b/zh.json index d265fe3e1..cbe84dd4d 100644 --- a/zh.json +++ b/zh.json @@ -177,7 +177,8 @@ "zh/deploy/ci", "zh/deploy/github", "zh/deploy/ghes", - "zh/deploy/gitlab" + "zh/deploy/gitlab", + "zh/deploy/gitlab-self-hosted" ] }, { diff --git a/zh/deploy/gitlab-self-hosted.mdx b/zh/deploy/gitlab-self-hosted.mdx new file mode 100644 index 000000000..1d87e78d8 --- /dev/null +++ b/zh/deploy/gitlab-self-hosted.mdx @@ -0,0 +1,84 @@ +--- +title: "自托管 GitLab" +description: "通过注册 OAuth 应用并在仪表板中配置连接，将你自行运行的 GitLab 实例连接到 Mintlify。" +keywords: ["自托管 GitLab", "GitLab OAuth", "GitLab Enterprise", "OAuth 应用"] +--- + +本指南介绍如何将自托管的 GitLab 实例连接到 Mintlify。你需要在 GitLab 实例上注册一个 OAuth 应用，然后在 Mintlify 仪表板中提供其客户端 ID 和密钥，以便工作流可以针对你的实例进行授权。 + +如果你使用 GitLab.com，请参阅 [GitLab](/zh/deploy/gitlab) 页面了解设置方法。 + +## 前提条件 + +- 拥有 GitLab 实例的管理员或维护者权限以注册 OAuth 应用 +- 你的 GitLab 实例具有可公开访问的 URL，以便 Mintlify 能够访问 +- 你的 Mintlify 仪表板已为组织启用 `Self-hosted GitLab OAuth` 功能 + +## 第 1 步：在 GitLab 实例上注册 OAuth 应用 + +在 GitLab 实例上注册一个新的 OAuth 应用。你可以根据访问范围在实例级、组级或用户级进行注册。 + + + + 在 GitLab 实例中，进入 **管理区域** > **应用** 以注册实例级应用，或进入 **用户设置** > **应用** 以在你的用户账户下注册。 + + + 设置以下字段： + + - **名称**：`Mintlify` + - **重定向 URI**：`https://leaves.mintlify.com/gitlab-oauth-webhook` + - **机密**：启用 + - **作用域**：`api`、`read_repository`、`write_repository` + + + `api` 作用域用于让 Mintlify 读取项目元数据并创建 webhook。`read_repository` 和 `write_repository` 作用域允许 Mintlify 克隆你的文档并推送预览部署。 + + + + 保存应用。GitLab 会显示 **Application ID**（客户端 ID）和 **Secret**（客户端密钥）。请在离开页面前记录这两项；密钥仅显示一次。 + + + +## 第 2 步：在 Mintlify 仪表板中连接你的实例 + + + + 在你的 [Mintlify 仪表板](https://dashboard.mintlify.com) 中，进入 **设置** > **Git 设置** > **GitLab OAuth**，然后定位到 **Self-hosted GitLab** 部分。 + + + 点击 **Connect Self-Hosted GitLab**，并填写以下字段： + + - **GitLab instance URL**：你实例的基础 URL，例如 `https://gitlab.your-company.com`。 + - **OAuth application client ID**：第 1 步中的 Application ID。 + - **OAuth application client secret**：第 1 步中的 Secret。 + + 点击 **Save instance**。你的客户端密钥在静态时已加密存储，并且在保存后永远不会通过 API 返回。 + + + 点击 **Authorize self-hosted GitLab**。系统会将你重定向到你的 GitLab 实例以批准 OAuth 应用，然后将你送回仪表板。 + + + 在安装列表中展开一个组，并选择要连接的项目。Mintlify 会在每个所选项目上启用 webhook，这样你推送更改时部署会自动触发。 + + + +## 轮换或移除凭据 + +要轮换 OAuth 凭据，请从 **Self-hosted GitLab** 部分移除现有实例，然后使用新的客户端 ID 和密钥重新添加。移除实例还会撤销通过该实例连接的所有活动安装。 + +## 故障排除 + + + + 自托管 GitLab OAuth 受组织级功能开关保护。请联系你的客户成功代表或 [support@mintlify.com](mailto:support@mintlify.com) 为你的组织启用该功能。 + + + 在 OAuth 应用上注册的重定向 URI 必须与 `https://leaves.mintlify.com/gitlab-oauth-webhook` 完全一致。请在 GitLab 上更新你的应用并重试。 + + + 你的实例必须可从公共互联网访问。请确认你的防火墙允许来自 Mintlify 的入站 HTTPS 连接，并且你的实例拥有有效的 SSL 证书。 + + + 授权 OAuth 应用的用户必须在每个已连接项目上至少拥有 **Maintainer** 角色。请使用具有所需角色的用户重新授权，或在受影响的项目上提升角色。 + +