自托管 GitLab OAuth
通过 OAuth 将自托管的 GitLab 实例连接到 Mintlify，让自动化能够代表你克隆存储库、推送提交和发起合并请求。
除了 gitlab.com 之外，Mintlify 还支持基于 OAuth 的自托管 GitLab 实例授权。OAuth 允许 Mintlify 代理在自动化运行期间以 GitLab 用户身份进行操作：克隆存储库、推送提交、发起合并请求以及注册项目 webhook。
你必须为自托管的 GitLab 实例配置 OAuth 授权，才能支持自动化。
与 gitlab.com 不同（Mintlify 提供单个 OAuth 应用供每位客户进行授权），每个自托管实例都必须注册自己的 OAuth 应用。请在你的 GitLab 实例上创建应用，将其凭据共享给 Mintlify，然后通过 OAuth 授权来连接用户。
本指南仅涉及为自动化提供支持的 OAuth 集成。你必须使用部署令牌单独配置部署端连接（用于内容同步和预览），请参阅 GitLab 指南。OAuth 集成依赖于部署端连接。
- 拥有自托管 GitLab 实例的管理员权限。
- 你的 GitLab 实例必须可以从
https://app.mintlify.com访问。位于 VPN 之后或被防火墙阻止公网入站访问的实例无法使用。 - 你的 Mintlify 组织已启用自托管 GitLab 功能。如果你在 Git 设置控制台页面中未看到 Self-hosted GitLab 部分，请联系支持团队。
Register an OAuth application on your GitLab instance
在自托管 GitLab 中，以管理员身份登录并依次前往 Admin Area > Applications > Add new application。
使用以下值配置应用：
- Name：
Mintlify - Redirect URI：
https://app.mintlify.com/api/gitlab-oauth/callback - Trusted：保持未勾选。将应用标记为 Trusted 会跳过每位用户的同意界面；保持未勾选状态可在每位用户首次连接时显示正常的授权提示。
- Confidential：勾选。Mintlify 是服务端客户端，会对密钥保密。
- Scopes：选择
api、read_repository和write_repository。代理会使用这些权限读取项目元数据、克隆存储库以及推送提交。
点击 Save application。
在 GitLab 上编辑 OAuth 应用可能会静默地轮换客户端密钥。如果你稍后做出更改，请点击 Renew secret 并在 Mintlify 中更新新的值。
Copy the application credentials
保存后，GitLab 会显示应用的 Application ID 和 Secret。请保持此页面打开——密钥只会显示一次。
Register the instance in Mintlify
在 Mintlify 控制台中，打开 Settings > Git settings，找到 GitLab OAuth 下的 Self-hosted GitLab 部分。
点击 Connect Self-Hosted GitLab 并输入：
- GitLab instance URL：你的 GitLab 实例的公网 URL，例如
https://gitlab.your-company.com。Mintlify 在交换令牌和调用 GitLab API 时会通过此 URL 访问你的实例。 - OAuth application client ID：上一步中的 Application ID。
- OAuth application client secret：上一步中的 Secret。
点击 Save instance。Mintlify 会对密钥进行静态加密，保存后绝不会再将其返回到浏览器。
Authorize
点击 Authorize self-hosted GitLab。GitLab 会将你重定向至你的实例，必要时提示登录，并显示列出所请求权限范围的同意界面。
在 GitLab 上点击 Authorize 之后，你会被重定向回 Mintlify，新建的连接将显示在已安装列表中，并以你的实例主机名作为标识。
Choose projects
在控制台中展开该连接。Mintlify 会列出授权用户拥有 Maintainer 或更高访问权限的每个群组，以及一个 Personal projects 条目（用于用户个人命名空间下的项目）。
勾选每个应参与自动化的项目旁的复选框。Mintlify 会在项目上注册 webhook，生成一个密钥令牌，并将其加密存储。从那时起，Mintlify 会接收你的实例针对该项目发送的推送和合并请求事件。
连接的用户必须在项目上具有 Maintainer 角色，Mintlify 才能在自动化运行期间生成短期项目访问令牌。没有 Maintainer 权限时，代理可以读取但无法推送提交或发起合并请求。
如果你需要更改已注册应用的客户端密钥——例如在 GitLab 上更新密钥后——请在 Mintlify 中删除已保存的实例，并使用新值重新添加。你必须先撤销活动的 OAuth 连接。否则，Mintlify 会阻止删除。
Revoke each connection
点击自托管实例下列出的每个安装上的 Revoke。这将移除每个已连接项目上的 webhook，并撤销 GitLab 上的 OAuth 令牌。
Remove the instance
在 Self-hosted GitLab 卡片中，点击 Remove instance。
Re-add with new credentials
使用新的客户端密钥按照前述的 Set up the connection 步骤进行操作。
GitLab 拒绝了令牌交换步骤，因为 Mintlify 发送的客户端密钥与应用上注册的不匹配。最常见的原因是 GitLab 上的密钥被轮换了——由显式的 Renew secret 操作触发，或在有人编辑应用时静默轮换——而 Mintlify 中的值已过时。
修复方法：使用当前密钥按照轮换凭据的步骤轮换凭据。
GitLab 拒绝注册 webhook，因为 GitLab 的出站请求白名单拒绝了 Mintlify 发送的 URL（https://app.mintlify.com/gitlab-oauth-webhook）。自托管实例会拒绝”本地”URL，除非管理员明确允许。
修复方法：在 GitLab 管理区域中，依次前往 Settings > Network > Outbound requests，启用 Allow requests to the local network from webhooks and integrations。如果你的网络策略阻止 app.mintlify.com，请联系网络管理员，允许出站 HTTPS 流量到达该主机。
如果你在授权时没有看到 GitLab 的同意对话框，可能是以下原因之一：
- 该应用在 GitLab 上带有 Trusted 标记。Trusted 应用会跳过所有用户的同意环节。如果你希望用户看到并确认权限范围，请在应用设置中取消勾选 Trusted。
- 你的 GitLab 用户之前已使用相同的权限范围授权了该应用。GitLab 会记住先前的授权，并在后续授权时跳过同意环节。请在 User settings > Applications > Authorized applications 中撤销该应用的授权，以再次查看同意界面。