Renovate Dependency Proxy Use
Renovate opens pull requests for new dependency versions. If Renovate looks up versions through the DevGuard dependency proxy, it only sees versions the proxy would also let you install:
- Versions blocked by your package rules, e.g. a minimum release age, are hidden.
- Versions flagged as malicious are hidden.
Renovate then proposes the newest allowed version instead of one your builds would fail to download.
Supported Ecosystems
| Ecosystem | Renovate datasource | Supported |
|---|---|---|
| npm | npm | ✓ |
| Go modules | go | ✓ |
| Maven | maven | ✓ |
| Composer | packagist | ✓ |
| Debian | deb | ✓ (via a custom manager, see Debian) |
| Alpine | apk | ✓ (via a custom manager, see Alpine) |
| PyPI | pypi | Not yet |
| OCI | docker | No – version lists are not filtered |
1. Get Your Proxy URL
Copy the proxy URLs from the Dependency Proxy settings of your organization, project or repository. They contain a secret, which tells DevGuard which package rules to apply:
https://<your-devguard-url>/api/v1/dependency-proxy/<secret>/npm/
Treat the secret like a credential. Everyone who can read your Renovate configuration can use the proxy with it.
2. Configure Renovate
Add a package rule per ecosystem to your renovate.json:
Go modules are the exception: Renovate reads the Go proxy from the GOPROXY environment variable, not from renovate.json. Set it where Renovate runs:
Do not append ,direct, otherwise Go bypasses the proxy when it rejects a version.
Debian
Renovate has no built-in manager for Debian packages, for example the versions pinned in a Dockerfile. Annotate each version with a comment and let a custom regex manager pick it up:
The configuration below uses managerFilePatterns and needs Renovate 41 or newer. The manager stores the suite as depType, so a package rule per suite can point Renovate at the matching proxy URL. Security updates live in the separate debian-security archive:
A Debian suite lists exactly one version per package. The proxy replaces a blocked version with the newest allowed older one (see How Debian packages are handled), so Renovate proposes this version instead.
Renovate verifies the downloaded package list against the checksums in InRelease, but not the signature. The proxy signs InRelease with its own key, so no extra configuration is needed. Only the suites listed in Setup Debian Proxy are supported.
Alpine
Alpine packages pinned in a Dockerfile are picked up the same way. Annotate each version with the Alpine branch and the package name:
The manager stores the branch as depType, so a package rule per branch can point Renovate at the matching proxy URL. The apk datasource builds the index URL from the query parameters branch, components and arch. arch is required:
The proxy removes blocked versions from the package index (APKINDEX.tar.gz). Currently the alpine proxy, unlike Debian, does not try to find an older version. This means Renovate reports a lookup warning in the Dependency Dashboard instead of opening a pull request for blocked packages.
3. Configure Your Package Managers
Renovate updates lock files (package-lock.json, go.sum, composer.lock) with the real package manager. Configure the proxy in your repository as well, so these downloads go through DevGuard too:
- Setup npm Proxy
- Setup Go Proxy
- Setup Maven Proxy
- Setup Composer Proxy
- Setup Debian Proxy
- Setup Alpine Proxy
What to Expect
| Situation | Renovate behavior |
|---|---|
| Newest version is too young for your minimum release age | Proposes the newest version that is old enough |
| A single version is malicious | Skips this version |
| Newest Debian version is blocked | Proposes the replacement version the proxy lists instead |
| Alpine version is blocked | The lookup fails and shows up as a warning in the Dependency Dashboard |
| All versions of a package are malicious | The lookup fails and shows up as a warning in the Dependency Dashboard |
With a minimum release age rule in DevGuard you do not need Renovate's own minimumReleaseAge. Renovate never sees the young versions, so it does not open pull requests for them at all.
Notes
- Renovate must be able to reach your DevGuard instance. With the hosted Renovate app, the proxy has to be publicly reachable.
- For Go, Renovate additionally contacts
golang.organd GitHub to find the source repository of a module. Versions are still only read from the proxy.