paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 29 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/getting-started/keeping-backstage-updated.md
+8 -5
View File
@@ -151,12 +151,14 @@ down the number of duplicate packages.
## Proxy
The Backstage CLI uses [global-agent](https://www.npmjs.com/package/global-agent) and `undici` to configure HTTP/HTTPS proxy settings using environment variables. This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access.
On Node.js 22.21.0+, the Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../tutorials/corporate-proxy.md) for full details.
On older Node.js versions, the CLI falls back to [global-agent](https://www.npmjs.com/package/global-agent) and `undici` for proxy support, which require their own environment variables (prefixed with `GLOBAL_AGENT_`). This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access.
Additionally, yarn needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the other modules. If you decide to use the backstage yarn plugin [mentioned above](#plugin), you will need to set additional proxy values.
If you will always need proxy settings in all environments and situations, you can add `httpProxy` and `httpsProxy` values to [the yarnrc.yml file](https://yarnpkg.com/configuration/yarnrc). If some environments need it (say a developer workstation) but other environments do not (perhaps a CI build server running on AWS), then you may not want to update the yarnrc.yml file but just set environment variables `YARN_HTTP_PROXY` and `YARN_HTTPS_PROXY` in the environments/situations where you need to proxy.
**If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the global agent proxy settings alone are sufficient.
**If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the proxy settings alone are sufficient.
### Example Configuration
@@ -164,9 +166,10 @@ If you will always need proxy settings in all environments and situations, you c
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://secure-proxy.company.com:8080
export NO_PROXY=localhost,internal.company.com
export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY}
export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY}
export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}
export NODE_USE_ENV_PROXY=1 # Node.js 22.21.0+
export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} # Node.js < 22.21.0
export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} # Node.js < 22.21.0
export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} # Node.js < 22.21.0
export YARN_HTTP_PROXY=${HTTP_PROXY} # optional
export YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional
```