feat(gitlab): support self-hosted GitLab instances (#146)

## Summary

The GitLab provider currently hardcodes `https://gitlab.com/api/v4`, so
connections can only target GitLab.com. Self-hosted GitLab (CE/EE)
deployments are very common, and the official GitLab CLI
([gitlab-org/cli](https://gitlab.com/gitlab-org/cli)) treats instance
host as a first-class setting (`GITLAB_HOST` / per-host config). This PR
brings the per-connection equivalent to the GitLab provider, following
the repo's self-hosted reference pattern (Dokploy, per AGENTS.md
"Provider Network Egress (SSRF)").

## Changes

- **`definition.ts`** – optional `baseUrl` ("Instance URL") extra field
on the `api_key` auth. Left empty, everything behaves exactly as before
(GitLab.com).
- **`executors.ts`** – executors now build a per-connection `apiBaseUrl`
via `normalizeGitlabApiBaseUrl`: defaults to
`https://gitlab.com/api/v4`, otherwise validates the instance URL with
the shared `assertPublicHttpUrl` SSRF guard (DNS validation stays on),
rejects embedded credentials, drops query/hash, and appends `/api/v4`.
Private/overlay targets stay blocked unless the deployment opts in via
`OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK`, mirroring Dokploy.
- **proxy** – removed the hardcoded `gitlab.com` entry from
`proxy.registry.ts` and exported a module proxy that derives its base
URL from the connection credential (`metadata.apiBaseUrl` /
`values.baseUrl`). Without this, `POST /v1/proxy/gitlab` would keep
sending a self-hosted instance's PAT to gitlab.com.
- **validator** – validates against the configured instance with a
re-guarded fetcher (so private instances validate when the deployment
allows it), stores the resolved `apiBaseUrl` in metadata, and scopes
account ids by instance host for self-hosted connections so the same
numeric user id on two instances never collides. GitLab.com account ids
are unchanged (`gitlab:<id>`).

## Backward compatibility

Existing GitLab.com connections are unaffected: empty/absent `baseUrl`
resolves to the previous hardcoded URL, account id format for GitLab.com
is untouched, and the proxy still defaults to
`https://gitlab.com/api/v4` when the credential carries no instance URL.

## Tests

- `network-access.test.ts` – URL normalization (default, subpath
instances, `/api/v4` idempotence, query/hash stripping, credential
rejection) and private-network gating (blocked by default, allowed with
the deployment flag, unsafe/metadata targets always blocked), plus
request routing to a configured instance.
- `egress-guard.test.ts` – validator blocks a redirect to a
cloud-metadata target, reaches a private instance when the deployment
opts in, and keeps the GitLab.com account id format.

`npm run fix-check` and `npm test` (600 passed) are green.

---------

Co-authored-by: Kevin Cui <bh@bugs.cc>

Author: ChasLui

src/providers/gitlab/definition.ts

@@ -19,6 +19,18 @@ export const provider: ProviderDefinition = {
       placeholder: "glpat-xxxxxxxxxxxxxxxxxxxx",
       description:
         "GitLab personal access token sent with the PRIVATE-TOKEN header. Create one in GitLab user preferences under Access tokens.",
+      extraFields: [
+        {
+          key: "baseUrl",
+          label: "Instance URL",
+          inputType: "text",
+          required: false,
+          secret: false,
+          placeholder: "https://gitlab.example.com",
+          description:
+            "Optional base URL of a self-hosted GitLab instance, without the /api/v4 path. Leave empty for GitLab.com. Private/overlay targets (RFC 1918, Tailscale, NetBird, private hostnames) require the self-hosted runtime to enable OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK.",
+        },
+      ],
     },
   ],
   homepageUrl: "https://gitlab.com",

src/providers/gitlab/egress-guard.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { setPrivateNetworkAccessAllowed } from "../../core/request.ts";
+import { credentialValidators } from "./executors.ts";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  setPrivateNetworkAccessAllowed(false);
+});
+
+function stubFetchSequence(responses: Response[]): Array<{ url: string }> {
+  const calls: Array<{ url: string }> = [];
+  vi.stubGlobal("fetch", async (input: RequestInfo | URL) => {
+    calls.push({ url: input instanceof Request ? input.url : String(input) });
+    const response = responses.shift();
+    if (!response) {
+      throw new Error("unexpected extra request");
+    }
+    return response;
+  });
+  return calls;
+}
+
+describe("GitLab validator egress guard", () => {
+  it("rejects a public baseUrl that redirects validation to a metadata target", async () => {
+    const calls = stubFetchSequence([
+      new Response(null, {
+        status: 302,
+        headers: { location: "http://169.254.169.254/latest/meta-data/" },
+      }),
+    ]);
+
+    await expect(
+      credentialValidators.apiKey!(
+        {
+          apiKey: "glpat-test",
+          values: { baseUrl: "https://gitlab.example.com" },
+        },
+        { fetcher: fetch },
+      ),
+    ).rejects.toThrow(/redirect location/u);
+    expect(calls).toHaveLength(1);
+  });
+
+  it("still reaches a private baseUrl when the deployment allows private networks", async () => {
+    setPrivateNetworkAccessAllowed(true);
+    const calls = stubFetchSequence([
+      new Response(JSON.stringify({ id: 7, username: "root", name: "Administrator" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    ]);
+
+    const result = await credentialValidators.apiKey!(
+      { apiKey: "glpat-test", values: { baseUrl: "http://10.0.0.5" } },
+      { fetcher: fetch },
+    );
+
+    if (!result) {
+      throw new Error("expected a validation result");
+    }
+    expect(calls[0]?.url).toBe("http://10.0.0.5/api/v4/user");
+    expect(result.profile?.accountId).toBe("gitlab:10.0.0.5:7");
+    expect(result.metadata?.apiBaseUrl).toBe("http://10.0.0.5/api/v4");
+  });
+
+  it("keeps the GitLab.com account id format for default connections", async () => {
+    const calls = stubFetchSequence([
+      new Response(JSON.stringify({ id: 42, username: "jane", name: "Jane" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    ]);
+
+    const result = await credentialValidators.apiKey!({ apiKey: "glpat-test", values: {} }, { fetcher: fetch });
+
+    if (!result) {
+      throw new Error("expected a validation result");
+    }
+    expect(calls[0]?.url).toBe("https://gitlab.com/api/v4/user");
+    expect(result.profile?.accountId).toBe("gitlab:42");
+    expect(result.metadata?.apiBaseUrl).toBe("https://gitlab.com/api/v4");
+  });
+});

src/providers/gitlab/executors.ts

@@ -1,4 +1,9 @@
-import type { CredentialValidators, ProviderExecutors } from "../../core/types.ts";
+import type {
+  CredentialValidators,
+  ExecutionContext,
+  ProviderExecutors,
+  ProviderProxyExecutor,
+} from "../../core/types.ts";
 import type { ApiKeyProviderContext } from "../provider-runtime.ts";
 
 import {
@@ -7,16 +12,26 @@ import {
   optionalIntegerLike,
   optionalString as asOptionalString,
 } from "../../core/cast.ts";
-import { defineApiKeyProviderExecutors, ProviderRequestError, providerUserAgent } from "../provider-runtime.ts";
-
-const gitlabApiBaseUrl = "https://gitlab.com/api/v4";
+import { assertPublicHttpUrl, isPrivateNetworkAccessAllowed } from "../../core/request.ts";
+import {
+  createProviderFetch,
+  defineProviderExecutors,
+  defineProviderProxy,
+  ProviderRequestError,
+  providerUserAgent,
+  requireApiKeyCredential,
+} from "../provider-runtime.ts";
+
+const defaultGitlabApiBaseUrl = "https://gitlab.com/api/v4";
 const service = "gitlab";
 
 type GitlabRequestPhase = "validate" | "execute";
 type GitlabActionInput = Record<string, unknown>;
 type GitlabActionHandler = (input: GitlabActionInput, context: GitlabActionContext) => Promise<unknown>;
 
-type GitlabActionContext = ApiKeyProviderContext;
+interface GitlabActionContext extends ApiKeyProviderContext {
+  apiBaseUrl: string;
+}
 
 interface GitlabRequestOptions {
   method?: "GET" | "POST";
@@ -43,23 +58,71 @@ export const gitlabActionHandlers: Record<string, GitlabActionHandler> = {
   },
 };
 
-export const executors: ProviderExecutors = defineApiKeyProviderExecutors(service, gitlabActionHandlers);
+export const executors: ProviderExecutors = defineProviderExecutors<GitlabActionContext>({
+  service,
+  handlers: gitlabActionHandlers,
+  async createContext(context: ExecutionContext, fetcher: typeof fetch): Promise<GitlabActionContext> {
+    const credential = await requireApiKeyCredential(context, service);
+    const providerContext: GitlabActionContext = {
+      apiKey: credential.apiKey,
+      apiBaseUrl: normalizeGitlabApiBaseUrl(credential.values.baseUrl),
+      fetcher,
+      signal: context.signal,
+    };
+    if (context.transitFiles) {
+      providerContext.transitFiles = context.transitFiles;
+    }
+    return providerContext;
+  },
+  allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+});
+
+export const proxy: ProviderProxyExecutor = defineProviderProxy({
+  service,
+  baseUrl: async (context) => {
+    const credential = await requireApiKeyCredential(context, service);
+    const value = asOptionalString(credential.metadata.apiBaseUrl) ?? asOptionalString(credential.values.baseUrl);
+    return normalizeGitlabApiBaseUrl(value);
+  },
+  auth: { type: "api_key_header", name: "private-token" },
+  allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+});
 
 export const credentialValidators: CredentialValidators = {
   async apiKey(input, { fetcher }) {
-    const user = await gitlabRequestJson("/user", { apiKey: input.apiKey, fetcher }, "validate");
+    const apiBaseUrl = normalizeGitlabApiBaseUrl(input.values.baseUrl);
+    // Re-guard the shared validator fetcher with GitLab's private-network
+    // opt-in so validating a self-hosted instance on a private network works
+    // when the deployment allows it (createProviderFetch unwraps an
+    // already-guarded fetcher).
+    const guardedFetcher = createProviderFetch({
+      fetch: fetcher,
+      allowPrivateNetwork: isPrivateNetworkAccessAllowed,
+    });
+    const user = await gitlabRequestJson(
+      "/user",
+      { apiKey: input.apiKey, apiBaseUrl, fetcher: guardedFetcher },
+      "validate",
+    );
     const userObject = asGitlabObject(user);
     const userId = readOptionalPrimitive(userObject.id);
     const username = asOptionalString(userObject.username);
     const name = asOptionalString(userObject.name);
+    // Scope the account id by instance host for self-hosted connections so the
+    // same numeric user id on different instances never collides.
+    const instanceHost = apiBaseUrl === defaultGitlabApiBaseUrl ? undefined : new URL(apiBaseUrl).host;
 
     return {
       profile: {
-        accountId: userId ? `gitlab:${userId}` : (username ?? "gitlab:user"),
+        accountId: instanceHost
+          ? `gitlab:${instanceHost}:${userId ?? username ?? "user"}`
+          : userId
+            ? `gitlab:${userId}`
+            : (username ?? "gitlab:user"),
         displayName: name ?? username ?? "GitLab User",
       },
       metadata: compactObject({
-        apiBaseUrl: gitlabApiBaseUrl,
+        apiBaseUrl,
         validationEndpoint: "/user",
         userId,
         username,
@@ -69,6 +132,42 @@ export const credentialValidators: CredentialValidators = {
   },
 };
 
+/**
+ * Resolves the GitLab API base URL for a connection. Empty input targets
+ * GitLab.com; otherwise the self-hosted instance URL is validated, embedded
+ * credentials are rejected, query/hash components are removed, and the path
+ * is ensured to end in `/api/v4`. Private/overlay targets (RFC 1918,
+ * Tailscale, NetBird, private hostnames) are only accepted when the
+ * deployment opts in through `OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK`;
+ * `allowPrivateNetwork` may be passed explicitly (used by tests).
+ */
+export function normalizeGitlabApiBaseUrl(
+  value: unknown,
+  allowPrivateNetwork: boolean = isPrivateNetworkAccessAllowed(),
+): string {
+  const instanceUrl = trimOptionalString(value);
+  if (!instanceUrl) {
+    return defaultGitlabApiBaseUrl;
+  }
+  const url = assertPublicHttpUrl(instanceUrl, {
+    fieldName: "baseUrl",
+    createError: credentialError,
+    allowPrivateNetwork,
+  });
+  if (url.username || url.password) {
+    throw credentialError("baseUrl must not include credentials");
+  }
+  url.hash = "";
+  url.search = "";
+  const path = url.pathname.replace(/\/+$/u, "");
+  url.pathname = path.endsWith("/api/v4") ? path : `${path}/api/v4`;
+  return url.toString().replace(/\/$/u, "");
+}
+
+function credentialError(message: string): ProviderRequestError {
+  return new ProviderRequestError(400, message);
+}
+
 async function listGitlabProjects(
   input: GitlabActionInput,
   context: GitlabActionContext,
@@ -174,7 +273,7 @@ async function gitlabRequest(
   context: GitlabActionContext,
   options: GitlabRequestOptions = {},
 ): Promise<Response> {
-  const url = new URL(`${gitlabApiBaseUrl}${path}`);
+  const url = new URL(`${context.apiBaseUrl}${path}`);
   for (const [key, value] of Object.entries(options.query ?? {})) {
     if (value !== undefined) {
       url.searchParams.set(key, String(value));