From a00f774f5aa3a9b3016b86f3dcda88ccc012ea77 Mon Sep 17 00:00:00 2001 From: LuxVTZ Date: Tue, 10 Mar 2026 19:29:23 +0400 Subject: [PATCH] Add GitLab Duo usage docs --- README.md | 5 ++ README_CN.md | 9 +++- docs/gitlab-duo.md | 115 ++++++++++++++++++++++++++++++++++++++++++ docs/gitlab-duo_CN.md | 115 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 243 insertions(+), 1 deletion(-) create mode 100644 docs/gitlab-duo.md create mode 100644 docs/gitlab-duo_CN.md diff --git a/README.md b/README.md index 4a482c03..ea308201 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,11 @@ The Plus release stays in lockstep with the mainline features. GitLab Duo is supported here via OAuth or personal access token login, with model discovery and provider-native routing through the GitLab AI gateway when managed credentials are available. +## Docs + +- GitLab Duo guide: [docs/gitlab-duo.md](docs/gitlab-duo.md) +- 中文说明: [docs/gitlab-duo_CN.md](docs/gitlab-duo_CN.md) + ## Contributing This project only accepts pull requests that relate to third-party provider support. Any pull requests unrelated to third-party provider support will be rejected. diff --git a/README_CN.md b/README_CN.md index bf83624e..ebc3e42f 100644 --- a/README_CN.md +++ b/README_CN.md @@ -8,6 +8,13 @@ 该 Plus 版本的主线功能与主线功能强制同步。 +GitLab Duo 已在这里接入，支持 OAuth 或 personal access token 登录，并在 GitLab 提供 managed credentials 时通过 GitLab AI gateway 做 provider-native 路由。 + +## 文档 + +- GitLab Duo 说明：[docs/gitlab-duo_CN.md](docs/gitlab-duo_CN.md) +- English guide: [docs/gitlab-duo.md](docs/gitlab-duo.md) + ## 贡献 该项目仅接受第三方供应商支持的 Pull Request。任何非第三方供应商支持的 Pull Request 都将被拒绝。 @@ -16,4 +23,4 @@ ## 许可证 -此项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 \ No newline at end of file +此项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 diff --git a/docs/gitlab-duo.md b/docs/gitlab-duo.md new file mode 100644 index 00000000..809737cb --- /dev/null +++ b/docs/gitlab-duo.md @@ -0,0 +1,115 @@ +# GitLab Duo guide + +CLIProxyAPI can now use GitLab Duo as a first-class provider instead of treating it as a plain text wrapper. + +It supports: + +- OAuth login +- personal access token login +- automatic refresh of GitLab `direct_access` metadata +- dynamic model discovery from GitLab metadata +- native GitLab AI gateway routing for Anthropic and OpenAI/Codex managed models +- Claude-compatible and OpenAI-compatible downstream APIs + +## What this means + +If GitLab Duo returns an Anthropic-managed model, CLIProxyAPI routes requests through the GitLab AI gateway Anthropic proxy and uses the existing Claude executor path. + +If GitLab Duo returns an OpenAI-managed model, CLIProxyAPI routes requests through the GitLab AI gateway OpenAI proxy and uses the existing Codex/OpenAI executor path. + +That gives GitLab Duo much closer runtime behavior to the built-in `codex` provider: + +- Claude-compatible clients can use GitLab Duo models through `/v1/messages` +- OpenAI-compatible clients can use GitLab Duo models through `/v1/chat/completions` +- OpenAI Responses clients can use GitLab Duo models through `/v1/responses` + +The model list is not hardcoded. CLIProxyAPI reads the current model metadata from GitLab `direct_access` and registers: + +- a stable alias: `gitlab-duo` +- any discovered managed model names, such as `claude-sonnet-4-5` or `gpt-5-codex` + +## Login + +OAuth login: + +```bash +./CLIProxyAPI -gitlab-login +``` + +PAT login: + +```bash +./CLIProxyAPI -gitlab-token-login +``` + +You can also provide inputs through environment variables: + +```bash +export GITLAB_BASE_URL=https://gitlab.com +export GITLAB_OAUTH_CLIENT_ID=your-client-id +export GITLAB_OAUTH_CLIENT_SECRET=your-client-secret +export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-... +``` + +Notes: + +- OAuth requires a GitLab OAuth application. +- PAT login requires a personal access token that can call the GitLab APIs used by Duo. In practice, `api` scope is the safe baseline. +- Self-managed GitLab instances are supported through `GITLAB_BASE_URL`. + +## Using the models + +After login, start CLIProxyAPI normally and point your client at the local proxy. + +You can select: + +- `gitlab-duo` to use the current Duo-managed model for that account +- the discovered provider model name if you want to pin it explicitly + +Examples: + +```bash +curl http://127.0.0.1:8080/v1/models +``` + +```bash +curl http://127.0.0.1:8080/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "gitlab-duo", + "messages": [ + {"role": "user", "content": "Write a Go HTTP middleware for request IDs."} + ] + }' +``` + +If the GitLab account is currently mapped to an Anthropic model, Claude-compatible clients can use the same account through the Claude handler path. If the account is currently mapped to an OpenAI/Codex model, OpenAI-compatible clients can use `/v1/chat/completions` or `/v1/responses`. + +## How model freshness works + +CLIProxyAPI does not ship a fixed GitLab Duo model catalog. + +Instead, it refreshes GitLab `direct_access` metadata and uses the returned `model_details` and any discovered model list entries to keep the local registry aligned with the current GitLab-managed model assignment. + +This matches GitLab's current public contract better than hardcoding model names. + +## Current scope + +The GitLab Duo provider now has: + +- OAuth and PAT auth flows +- runtime refresh of Duo gateway credentials +- native Anthropic gateway routing +- native OpenAI/Codex gateway routing +- handler-level smoke tests for Claude-compatible and OpenAI-compatible paths + +Still out of scope today: + +- websocket or session-specific parity beyond the current HTTP APIs +- GitLab-specific IDE features that are not exposed through the public gateway contract + +## References + +- GitLab Code Suggestions API: https://docs.gitlab.com/api/code_suggestions/ +- GitLab Agent Assistant and managed credentials: https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/ +- GitLab Duo model selection: https://docs.gitlab.com/user/gitlab_duo/model_selection/ diff --git a/docs/gitlab-duo_CN.md b/docs/gitlab-duo_CN.md new file mode 100644 index 00000000..1c21d1cf --- /dev/null +++ b/docs/gitlab-duo_CN.md @@ -0,0 +1,115 @@ +# GitLab Duo 使用说明 + +CLIProxyAPI 现在可以把 GitLab Duo 当作一等 Provider 来使用，而不是仅仅把它当成简单的文本补全封装。 + +当前支持： + +- OAuth 登录 +- personal access token 登录 +- 自动刷新 GitLab `direct_access` 元数据 +- 根据 GitLab 返回的元数据动态发现模型 +- 针对 Anthropic 和 OpenAI/Codex 托管模型的 GitLab AI gateway 原生路由 +- Claude 兼容与 OpenAI 兼容下游 API + +## 这意味着什么 + +如果 GitLab Duo 返回的是 Anthropic 托管模型，CLIProxyAPI 会通过 GitLab AI gateway 的 Anthropic 代理转发，并复用现有的 Claude executor 路径。 + +如果 GitLab Duo 返回的是 OpenAI 托管模型，CLIProxyAPI 会通过 GitLab AI gateway 的 OpenAI 代理转发，并复用现有的 Codex/OpenAI executor 路径。 + +这让 GitLab Duo 的运行时行为更接近内置的 `codex` Provider： + +- Claude 兼容客户端可以通过 `/v1/messages` 使用 GitLab Duo 模型 +- OpenAI 兼容客户端可以通过 `/v1/chat/completions` 使用 GitLab Duo 模型 +- OpenAI Responses 客户端可以通过 `/v1/responses` 使用 GitLab Duo 模型 + +模型列表不是硬编码的。CLIProxyAPI 会从 GitLab `direct_access` 中读取当前模型元数据，并注册： + +- 一个稳定别名：`gitlab-duo` +- GitLab 当前发现到的托管模型名，例如 `claude-sonnet-4-5` 或 `gpt-5-codex` + +## 登录 + +OAuth 登录： + +```bash +./CLIProxyAPI -gitlab-login +``` + +PAT 登录： + +```bash +./CLIProxyAPI -gitlab-token-login +``` + +也可以通过环境变量提供输入： + +```bash +export GITLAB_BASE_URL=https://gitlab.com +export GITLAB_OAUTH_CLIENT_ID=your-client-id +export GITLAB_OAUTH_CLIENT_SECRET=your-client-secret +export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-... +``` + +说明： + +- OAuth 方式需要一个 GitLab OAuth application。 +- PAT 登录需要一个能够调用 GitLab Duo 相关 API 的 personal access token。实践上，`api` scope 是最稳妥的基线。 +- 自建 GitLab 实例可以通过 `GITLAB_BASE_URL` 接入。 + +## 如何使用模型 + +登录完成后，正常启动 CLIProxyAPI，并让客户端连接到本地代理。 + +你可以选择： + +- `gitlab-duo`，始终使用该账号当前的 Duo 托管模型 +- GitLab 当前发现到的 provider 模型名，如果你想显式固定模型 + +示例： + +```bash +curl http://127.0.0.1:8080/v1/models +``` + +```bash +curl http://127.0.0.1:8080/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "gitlab-duo", + "messages": [ + {"role": "user", "content": "Write a Go HTTP middleware for request IDs."} + ] + }' +``` + +如果该 GitLab 账号当前绑定的是 Anthropic 模型，Claude 兼容客户端可以通过 Claude handler 路径直接使用它。如果当前绑定的是 OpenAI/Codex 模型，OpenAI 兼容客户端可以通过 `/v1/chat/completions` 或 `/v1/responses` 使用它。 + +## 模型如何保持最新 + +CLIProxyAPI 不内置固定的 GitLab Duo 模型清单。 + +它会刷新 GitLab `direct_access` 元数据，并使用返回的 `model_details` 以及可能存在的模型列表字段，让本地 registry 尽量与 GitLab 当前分配的托管模型保持一致。 + +这比硬编码模型名更符合 GitLab 当前公开 API 的实际契约。 + +## 当前覆盖范围 + +GitLab Duo Provider 目前已经具备： + +- OAuth 和 PAT 登录流程 +- Duo gateway 凭据的运行时刷新 +- Anthropic gateway 原生路由 +- OpenAI/Codex gateway 原生路由 +- Claude 兼容和 OpenAI 兼容路径的 handler 级 smoke 测试 + +当前仍未覆盖： + +- websocket 或 session 级别的完全对齐 +- GitLab 公开 gateway 契约之外的 IDE 专有能力 + +## 参考资料 + +- GitLab Code Suggestions API: https://docs.gitlab.com/api/code_suggestions/ +- GitLab Agent Assistant 与 managed credentials: https://docs.gitlab.com/user/duo_agent_platform/agent_assistant/ +- GitLab Duo 模型选择: https://docs.gitlab.com/user/gitlab_duo/model_selection/