feat: add upstream proxy configuration for outbound requests

config.schema.json

@@ -367,6 +367,29 @@
           }
         }
       }
+    },
+    "upstreamProxy": {
+      "description": "Configuration for routing outbound requests to upstream Git hosts via an HTTP(S) proxy.",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether to use an outbound HTTP(S) proxy for upstream Git hosts."
+        },
+        "url": {
+          "type": "string",
+          "description": "Proxy URL used for outbound connections to upstream Git hosts when set.",
+          "format": "uri"
+        },
+        "noProxy": {
+          "type": "array",
+          "description": "Additional hostnames or domain suffixes that should bypass the upstream proxy.",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "definitions": {

docs/Architecture.md

@@ -222,6 +222,26 @@ Currently supports the following out-of-the-box:
 - ActiveDirectory auth configuration for querying via a REST API rather than LDAP
 - Gitleaks configuration
 
+#### `upstreamProxy`
+
+Configures routing of outbound requests from the GitProxy server to upstream Git hosts (e.g. GitHub, GitLab) via an HTTP(S) proxy. Use this when the server runs in an environment where direct Internet access is not allowed and all traffic must go through a corporate web proxy ("proxying the proxy").
+
+- **`enabled`** (boolean): When `true`, outbound connections to upstream Git hosts use the configured proxy. When `false`, the proxy is not used even if `url` or environment variables are set.
+- **`url`** (string): The HTTP(S) proxy URL (e.g. `http://proxy.corp.local:8080` or `http://user:pass@proxy.corp.local:8080`). If omitted, GitProxy falls back to the `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY` or `http_proxy` environment variables (first defined wins).
+- **`noProxy`** (array of strings, optional): Hostnames or domain suffixes for which the proxy should be bypassed (e.g. internal Git hosts). Combined with the `NO_PROXY` / `no_proxy` environment variable.
+
+Example:
+
+```json
+"upstreamProxy": {
+  "enabled": true,
+  "url": "http://proxy.corp.local:8080",
+  "noProxy": ["github.corp.local", "gitlab.corp.local"]
+}
+```
+
+If `upstreamProxy` is not configured, setting only `HTTPS_PROXY` (or `HTTP_PROXY`) in the environment will also enable use of that proxy for outbound connections, unless `enabled` is explicitly set to `false` in config.
+
 #### `commitConfig`
 
 Used in [`checkCommitMessages`](./Processors.md#checkcommitmessages), [`checkAuthorEmails`](./Processors.md#checkauthoremails) and [`scanDiff`](./Processors.md#scandiff) processors to block pushes depending on the given rules.

package.json

@@ -117,6 +117,7 @@
     "express-session": "^1.19.0",
     "font-awesome": "^4.7.0",
     "history": "5.3.0",
+    "https-proxy-agent": "^7.0.6",
     "isomorphic-git": "^1.36.3",
     "jsonwebtoken": "^9.0.3",
     "load-plugin": "^6.0.3",

proxy.config.json

@@ -156,6 +156,11 @@
       }
     }
   ],
+  "upstreamProxy": {
+    "enabled": false,
+    "url": "http://localhost:8081",
+    "noProxy": []
+  },
   "tls": {
     "enabled": false,
     "key": "certs/key.pem",

src/config/generated/config.ts

@@ -101,6 +101,10 @@ export interface GitProxyConfig {
    * UI routes that require authentication (logged in or admin)
    */
   uiRouteAuth?: UIRouteAuth;
+  /**
+   * Configuration for routing outbound requests to upstream Git hosts via an HTTP(S) proxy.
+   */
+  upstreamProxy?: UpstreamProxy;
   /**
    * Customisable URL shortener to share in proxy responses and warnings
    */
@@ -563,6 +567,24 @@ export interface RouteAuthRule {
   [property: string]: any;
 }
 
+/**
+ * Configuration for routing outbound requests to upstream Git hosts via an HTTP(S) proxy.
+ */
+export interface UpstreamProxy {
+  /**
+   * Whether to use an outbound HTTP(S) proxy for upstream Git hosts.
+   */
+  enabled?: boolean;
+  /**
+   * Additional hostnames or domain suffixes that should bypass the upstream proxy.
+   */
+  noProxy?: string[];
+  /**
+   * Proxy URL used for outbound connections to upstream Git hosts when set.
+   */
+  url?: string;
+}
+
 // Converts JSON strings to/from your types
 // and asserts the results of JSON.parse at runtime
 export class Convert {
@@ -780,6 +802,7 @@ const typeMap: any = {
       { json: 'tempPassword', js: 'tempPassword', typ: u(undefined, r('TempPassword')) },
       { json: 'tls', js: 'tls', typ: u(undefined, r('TLS')) },
       { json: 'uiRouteAuth', js: 'uiRouteAuth', typ: u(undefined, r('UIRouteAuth')) },
+      { json: 'upstreamProxy', js: 'upstreamProxy', typ: u(undefined, r('UpstreamProxy')) },
       { json: 'urlShortener', js: 'urlShortener', typ: u(undefined, '') },
     ],
     false,
@@ -981,6 +1004,14 @@ const typeMap: any = {
     ],
     'any',
   ),
+  UpstreamProxy: o(
+    [
+      { json: 'enabled', js: 'enabled', typ: u(undefined, true) },
+      { json: 'noProxy', js: 'noProxy', typ: u(undefined, a('')) },
+      { json: 'url', js: 'url', typ: u(undefined, '') },
+    ],
+    false,
+  ),
   AuthenticationElementType: ['ActiveDirectory', 'jwt', 'local', 'openidconnect'],
   DatabaseType: ['fs', 'mongo'],
 };

src/config/index.ts

@@ -149,6 +149,23 @@ export const getProxyUrl = (): string | undefined => {
   return config.proxyUrl;
 };
 
+/**
+ * Redacts the userinfo (credentials) from a proxy URL for safe logging.
+ * e.g. http://user:pass@proxy.corp.local:8080 → http://<redacted>@proxy.corp.local:8080
+ *
+ * WARNING: proxyUrl may contain plaintext credentials in the userinfo portion.
+ * Never log a raw proxy URL — always pass it through this helper first.
+ */
+export const redactProxyUrl = (url: string): string => {
+  return url.replace(/^(https?:\/\/)[^@]+@/, '$1<redacted>@');
+};
+
+// Get upstream proxy configuration
+export const getUpstreamProxyConfig = () => {
+  const config = loadFullConfiguration();
+  return config.upstreamProxy || {};
+};
+
 // Gets a list of authorised repositories
 export const getAuthorisedList = () => {
   const config = loadFullConfiguration();

src/proxy/routes/index.ts

@@ -23,6 +23,9 @@ import { processUrlPath, validGitRequest } from './helper';
 import { getAllProxiedHosts } from '../../db';
 import { ProxyOptions } from 'express-http-proxy';
 import { handleErrorAndLog } from '../../utils/errors';
+import { getUpstreamProxyConfig } from '../../config';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { OutgoingHttpHeaders, RequestOptions } from 'http';
 
 enum ActionType {
   ALLOWED = 'Allowed',
@@ -144,7 +147,123 @@ const getRequestPathResolver: (prefix: string) => ProxyOptions['proxyReqPathReso
   };
 };
 
-const proxyReqOptDecorator: ProxyOptions['proxyReqOptDecorator'] = (proxyReqOpts) => proxyReqOpts;
+const getEnvProxyUrl = () =>
+  process.env.HTTPS_PROXY ||
+  process.env.https_proxy ||
+  process.env.HTTP_PROXY ||
+  process.env.http_proxy;
+
+const getEnvNoProxyList = (): string[] => {
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+  if (!noProxy) {
+    return [];
+  }
+  return noProxy
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+};
+
+const hostMatchesNoProxy = (host: string | null | undefined, noProxyList: string[]): boolean => {
+  if (!host) {
+    return false;
+  }
+
+  const hostname = host.split(':')[0];
+
+  return noProxyList.some((pattern) => {
+    if (!pattern) {
+      return false;
+    }
+
+    const trimmed = pattern.trim().replace(/^\./, ''); // strip leading dot
+    if (trimmed === '*') return true; // wildcard - bypass all
+
+    if (trimmed === '') {
+      return false;
+    }
+
+    // Exact match
+    if (hostname === trimmed) {
+      return true;
+    }
+
+    // Domain suffix match, e.g. example.com matches foo.example.com
+    if (hostname.endsWith(`.${trimmed}`)) {
+      return true;
+    }
+
+    return false;
+  });
+};
+
+// WARNING: proxyUrl may contain plaintext credentials in the userinfo portion
+// (e.g. http://user:pass@proxy.corp.local:8080). Never log it directly — use
+// redactProxyUrl() from config for any log statements involving this value.
+let _cachedProxyAgent: { proxyUrl: string; agent: HttpsProxyAgent<string> } | null = null;
+
+const getOrCreateProxyAgent = (proxyUrl: string): HttpsProxyAgent<string> => {
+  if (!_cachedProxyAgent || _cachedProxyAgent.proxyUrl !== proxyUrl) {
+    let parsed: URL;
+    try {
+      parsed = new URL(proxyUrl);
+    } catch {
+      throw new Error(
+        `Invalid upstream proxy URL: check your upstreamProxy.url config or HTTPS_PROXY env var`,
+      );
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error(
+        `Unsupported upstream proxy URL scheme "${parsed.protocol.replace(/:$/, '')}": only http and https are supported`,
+      );
+    }
+    if (!parsed.hostname) {
+      throw new Error(
+        `Invalid upstream proxy URL: hostname is missing — check your upstreamProxy.url config or HTTPS_PROXY env var`,
+      );
+    }
+    _cachedProxyAgent = { proxyUrl, agent: new HttpsProxyAgent(proxyUrl) };
+  }
+  return _cachedProxyAgent.agent;
+};
+
+const buildUpstreamProxyAgent = (
+  proxyReqOpts: Omit<RequestOptions, 'headers'> & {
+    headers: OutgoingHttpHeaders;
+  },
+) => {
+  const { enabled, url, noProxy } = getUpstreamProxyConfig();
+
+  const proxyUrl = url || getEnvProxyUrl();
+
+  // If enabled is not existant or false
+  if (enabled === undefined || enabled === false || !proxyUrl) {
+    return undefined;
+  }
+
+  const host: string | null | undefined = proxyReqOpts.host || proxyReqOpts.hostname;
+
+  const combinedNoProxy = [...(noProxy || []), ...getEnvNoProxyList()];
+
+  if (hostMatchesNoProxy(host, combinedNoProxy)) {
+    return undefined;
+  }
+
+  return getOrCreateProxyAgent(proxyUrl);
+};
+
+const proxyReqOptDecorator: ProxyOptions['proxyReqOptDecorator'] = (proxyReqOpts, _srcReq) => {
+  const agent = buildUpstreamProxyAgent(proxyReqOpts);
+
+  if (!agent) {
+    return proxyReqOpts;
+  }
+
+  return {
+    ...proxyReqOpts,
+    agent,
+  };
+};
 
 const proxyReqBodyDecorator: ProxyOptions['proxyReqBodyDecorator'] = (bodyContent, srcReq) => {
   if (srcReq.method === 'GET') {
@@ -273,4 +392,7 @@ export {
   isPackPost,
   extractRawBody,
   validGitRequest,
+  buildUpstreamProxyAgent,
+  hostMatchesNoProxy,
+  getOrCreateProxyAgent,
 };