paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

docs: recommend Node.js built-in proxy support for corporate proxies (#33006)

Browse Source 
Node.js 22.21.0+ natively supports HTTP_PROXY, HTTPS_PROXY, and
NO_PROXY environment variables via NODE_USE_ENV_PROXY, eliminating the
need for undici and global-agent workarounds. This also works with
node-fetch and cross-fetch since they delegate to node:http/node:https
without overriding the HTTP agent.

Add a new corporate proxy tutorial under docs/ with the recommended
approach and update the legacy guide in contrib/ to point to it.
Update proxy references in the deployment, keeping-backstage-updated,
and TechDocs CLI docs to mention NODE_USE_ENV_PROXY.

Signed-off-by: Jon Koops <jonkoops@gmail.com>
This commit is contained in:
Jon Koops
2026-03-17 18:13:00 +01:00
committed by GitHub
parent f60c2673ce
commit 956133bf45
6 changed files with 59 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/cli.md
+5 -2
View File
@@ -208,10 +208,13 @@ Options:
#### Publishing from behind a proxy
For users attempting to publish TechDocs content behind a proxy, the TechDocs CLI leverages `global-agent` to navigate the proxy to successfully connect to that location. To enable `global-agent`, the following variables need to be set prior to running the techdocs-cli command:
On Node.js 22.21.0+, set `NODE_USE_ENV_PROXY=1` along with `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` to route TechDocs publishing through a proxy. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for details.
On older Node.js versions, the TechDocs CLI leverages `global-agent` to navigate the proxy. To enable `global-agent`, the following variables need to be set prior to running the techdocs-cli command:
```bash
export GLOBAL_AGENT_HTTPS_PROXY=${HTTP_PROXY}
export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY}
export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY}
export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}
```