Upstream proxy
What Is an Upstream Proxy?
An upstream proxy is a registry that fetches packages from an external source on demand and serves them to your builds. Think of it as a trusted middleman between your developers and public registries such as npm, PyPI or Maven Central.
How an Upstream Proxy Works
| Step | What happens |
|---|---|
| Request | A build asks the proxy for a package |
| Lookup | The proxy checks its local store, then configured upstream sources in priority order |
| Fetch | If the package is missing, the proxy retrieves it from the upstream source |
| Serve | The package is returned to the client, and may be cached for later requests |
Why Upstream Proxies Matter
Routing dependencies through one point brings several benefits:
- Builds keep working during public registry outages
- Packages removed upstream stay available
- One place to see what teams consume
- A point to apply security and license checks
Visibility and control come from the same change.
Proxying vs Caching
Proxying passes each request through to the upstream source. Caching stores a copy so later requests are served locally. Most proxies do both, and caching is what protects builds when the source goes down.
Final Thought
An upstream proxy turns public registries from a direct dependency into a managed one. It makes external packages predictable.
Frequently asked questions
Is an upstream proxy the same as a mirror?
Not quite. A mirror copies an entire source in advance, while a proxy fetches only the packages that are requested.
Does an upstream proxy make dependencies safe?
No. It centralizes access, but safety depends on the scanning and policy checks applied to what it serves.
Can an upstream proxy cause stale packages?
It can if cached metadata is not refreshed. Most proxies let you set how long cached data is trusted.
Which package formats can be proxied?
Common examples include npm, Python, Maven, Go, NuGet and container images. Support varies by tool.
What happens when two upstreams have the same package?
The proxy follows a configured priority order, so the higher-priority source wins.