How do you centralize Gradle repositories and block project ones?

Declare repositories once in settings.gradle.kts under dependencyResolutionManagement, then set repositoriesMode to FAIL_ON_PROJECT_REPOS. Any subproject or plugin that adds its own repository then fails the build, so the list of places your dependencies can come from lives in one reviewed file.

Why default behavior is loose

Gradle's documentation says that by default, repositories declared in a project's build file override those in settings. That mode is called PREFER_PROJECT, and it is the default. It suits teams who need different repositories per project, but it also means any build file, in any subproject, can add a download source, and review of that file is easy to skip.

Central declaration of repositories is described as an incubating feature, so check the current documentation for your Gradle version before rolling it out widely.

The three modes

Set it up

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
    }
}

Then remove repositories blocks from subproject build files and from any shared convention plugin. The first build will tell you every place that still declares one.

Steps

1. Inventory current repositories with a search for repositories blocks across build files and convention plugins.
2. Move the ones you need into settings, using your internal repository URL.
3. Add content filters to keep internal groups on the internal repository. See Gradle exclusiveContent.
4. Switch to FAIL_ON_PROJECT_REPOS and fix whatever breaks.
5. Add a code owner on settings.gradle.kts so changes to the list are always reviewed.

Reusing Maven mirror settings

The documentation also describes an incubating option for organizations that already use an internal repository manager through a mirror in the Maven settings file. Gradle can read those mirror definitions, so Maven and Gradle builds in the same company can share one source of truth. The page lists unsupported mirror settings, so read it before depending on this.

A worked example

Say a company has twelve subprojects and three of them declare an extra repository for an old internal library. With the default mode, nothing complains, and a reviewer reading a pull request for one subproject has no reason to look at the others. After switching to FAIL_ON_PROJECT_REPOS, the first build names each offender. You then decide, one by one, whether the library should move into the internal repository manager or be retired.

The result is a single short list of allowed sources, in one file, that a security reviewer can read in a minute. That is a much easier thing to audit than twelve build files.

Things that can still surprise you

Plugin repositories are configured separately from dependency repositories, so review that part of your settings file on its own. Publishing is not affected by this setting, according to the documentation.

Keep in mind what this control does and does not do. It limits where dependencies can come from. It does not check what they contain. Pair it with scanning.

Safeguard scans the libraries your Gradle builds resolve, produces SBOMs, and gates pull requests on policy, so a new dependency with a serious finding is caught before merge. Try a free scan at gold.safeguard.sh/scan.

Quick check

Sources

• Centralizing Repository Declarations, Gradle documentation

Last reviewed: 19 October 2026.