Outbound proxy support for air-gapped / corporate network environments

[coopernetes]

Summary

In many organisations, servers don't have direct internet access — outbound connections must go through a corporate HTTP proxy. jgit-proxy currently assumes direct internet access when forwarding to upstream SCM providers. There's no way to configure an outbound proxy, making the proxy unusable in these environments.

Three outbound connection paths

Unlike a simple HTTP middleware, jgit-proxy has three distinct places that open outbound connections, each using a different library. All three need proxy support:

1. Store-and-forward upstream push — ForwardingPostReceiveHook uses JGit's Transport.open(). JGit respects Java system properties (https.proxyHost, https.proxyPort, http.nonProxyHosts) but there's no way to set these from the YAML config today.

2. Transparent proxy forwarding — GitProxyServlet (Jetty's ProxyServlet) uses Jetty's internal HttpClient. Proxy support requires calling httpClient.getProxyConfiguration().addProxy(new HttpProxy(host, port)) at servlet setup time in GitProxyServletRegistrar.registerProxyServlet().

3. Provider SCM API calls (identity resolution, etc.) — GitHubProvider, GitLabProvider, etc. use Apache HttpClient 5 via org.apache.hc.client5.http.fluent.Request. These need a RequestConfig or RoutePlanner configured with the proxy host/port.

The upstream Node.js implementation hooks proxy configuration into proxyReqOptDecorator in src/proxy/routes/index.ts (line 147, currently a no-op pass-through) — this only covers path 2. jgit-proxy needs all three covered.

Proposed configuration

New server.outboundProxy block alongside the existing timeout settings:

server:
  outboundProxy:
    host: proxy.corp.example.com
    port: 8080
    # Optional: skip proxy for these hosts (matches Java nonProxyHosts syntax)
    noProxy: "localhost|*.internal.example.com"

At startup:

• Set https.proxyHost / https.proxyPort / http.nonProxyHosts as system properties (covers JGit Transport)
• Pass proxy config into Jetty HttpClient in registerProxyServlet() (covers transparent proxy)
• Build a shared Apache HC5 HttpClientBuilder with DefaultProxyRoutePlanner and inject it into all provider implementations (covers SCM API calls)

Documentation

The Node.js issue notes this is primarily a documentation gap for end users discovering the proxy in air-gapped environments. Alongside the config support, docs/CONFIGURATION.md should include a worked example for the corporate proxy case.

[coopernetes]

Auth is another thing. Need support for Basic Auth (username & password) + NTLM (typical in Windows environments).

http.auth.ntlm.domain

There is no builtin java property for basic auth via HTTP proxy. JGit transport's HTTP client would need auth wired in.

[coopernetes]

Splitting this into two scopes:

1.0.0 (this issue, trimmed scope): env-var proxy wiring only — read HTTP_PROXY / HTTPS_PROXY / NO_PROXY at startup and wire into all three outbound paths (JGit Transport, Jetty HttpClient, Apache HC5). No auth support, no new YAML config. This covers the common corporate dev setup where cntlm/Alpaca runs as a local relay at e.g. http://localhost:3128 and handles auth upstream.

Post-1.0.0 (new issue): full server.outboundProxy YAML config block with NTLM and Basic auth support across all three paths. NTLM in particular is non-trivial with HC5 and warrants its own issue.

[coopernetes]

Also worth noting in docs (added to ADMIN_GUIDE.md): enterprises with DLP appliances that block non-GET traffic to SCM hosts will see pushes fail at the upstream forwarding step even with a proxy configured. The fix is an egress IP allowlist for POST/PUT at the network level, not something the proxy can work around. SSL inspection (MITM) is a related gotcha — the proxy host's egress should bypass inspection or JGit certificate validation will break.