To use a private mirror of Maven Central, run a repository manager that proxies and caches Central, then add a mirror entry to settings.xml with mirrorOf set to central. Every build then resolves through your server, giving you one place for caching, access control and scanning.
What does Maven's mirror setting do?
The Maven guide on mirror settings gives three reasons to use one: a closer or faster synchronized mirror, replacing a repository with your own internal one that you control, and running a repository manager as a local cache by using its URL. The last two are the security-relevant ones.
You configure it in the settings file under your home directory's .m2 folder. Each mirror has an id, a name, a url and a mirrorOf value naming the repository it stands in for. Central's id is central.
What are the gotchas?
Maven's guide notes that there can be at most one mirror for a given repository. You cannot map a single repository to a group of mirrors that all use the same mirrorOf value. Maven picks the first match and does not aggregate them. If you want a combined view of several repositories, use a repository manager and point Maven at its group URL.
Also remember mirrors apply to repositories declared in project files too. A dependency pulled from a repository defined in a pom can be redirected through your mirror, which is what you want if you set it up to match all repositories. The guide explains the wildcard options for mirrorOf, so read them before choosing one.
Why not just trust the mirror?
A mirror reduces exposure to the public internet at build time, and it keeps working if Central is down for a cached artifact. It does not decide what is safe. A bad artifact fetched once is served to everyone. Treat the repository manager as a gate: scan on download, apply allow and block rules, and keep logs of what each build pulled.
A constructed example: a team's mirror proxies Central and a snapshot repository. A developer adds a dependency with a name one letter off from a popular library. Because all traffic goes through the mirror, the new coordinates appear in the access log on first fetch, and a rule that holds brand-new components for review catches it before the build farm uses it.
What should the repository manager do on first fetch?
The first request for an artifact is the moment of greatest risk, because after that the copy is trusted by everyone. Configure the manager to check the artifact against vulnerability data and your allow and block rules before serving it. Some teams also hold components published in the last few days until someone has looked at them, since many malicious packages are found quickly after release.
How to check or apply this
- Deploy a repository manager with a proxy repository for Central, behind TLS and authentication.
- Create a group repository if you need Central plus internal artifacts in one URL.
- Add the mirror entry to settings.xml on developer machines and CI agents, using the group URL.
- Block direct access to Central from build networks so the setting cannot be bypassed.
- Turn on component scanning and quarantine for newly proxied artifacts.
- Keep checksum and signature verification enabled in your builds.
- Review the pull logs on a schedule, and when an advisory lands, search them first.
Safeguard can scan project dependencies and enforce policy gates in CI, which complements the mirror.
Quick check
Can I list two mirrors for Central in settings.xml?
Not usefully. Maven's guide says at most one mirror applies per repository and it picks the first match. Use a repository manager group to combine sources.
Does a mirror stop malicious packages?
No. It caches what it fetched. Add scanning, quarantine rules and logs to make it a control point.
Sources
Last reviewed: 18 October 2026.
