Where do Gradle plugins come from, and how do I control the source?

By default, plugins in a Gradle plugins block resolve from the public Gradle Plugin Portal. You control that in the settings file with a pluginManagement repositories block, which is separate from the repositories used for your project dependencies. Pin plugin versions in one place so a build never drifts.

Two sets of repositories

Gradle keeps plugin repositories apart from dependency repositories. The docs state that when resolving project dependencies, Gradle uses only the repositories in the build script and ignores the plugin repositories. The reverse is also true: a repository you add for libraries does not supply plugins.

This split surprises teams that lock down library repositories carefully and forget the plugin side. A build plugin runs inside the build with the same reach as your own build scripts, so its source matters at least as much as a library's.

Choosing the source

Add repositories to pluginManagement in settings.gradle.kts. Gradle searches them in the order declared, and if you leave out the portal entry it is not searched at all. A typical internal setup lists only your approved mirror:

pluginManagement {
    repositories {
        maven {
            url = uri("https://repo.example.com/gradle-plugins")
        }
    }
}

An init script can set the same thing for every build on a machine, which is useful for CI images.

How a plugin is found

For a plugin with an id, Gradle looks for a marker artifact named after the id plus the suffix gradle.plugin, which depends on the real implementation module. This matters for filtering: if you restrict a repository by group, allow the marker group as well as the implementation group, or resolution will fail in a confusing way.

Pin the version in one place

Gradle documents several places to fix a plugin version:

1. Inline in the plugins block of a build script, as a constant string.
2. Centrally in the plugins section of pluginManagement in settings, where the value can come from gradle.properties.
3. In the plugins section of a version catalog, applied with an alias.

Pick one and use it everywhere. The Gradle page on this topic describes exact versions as the way to fix a plugin version, and does not describe ranges, lock files or checksum checks for plugins. Treat that as a gap to close in your own process: review plugin version changes in pull requests the way you review library bumps.

A short review checklist

1. List every plugin id in the build, including settings plugins.
2. Confirm each resolves from a source you chose.
3. Remove plugins nobody can explain.
4. Check who maintains each remaining plugin and how often it ships.
5. Put plugin version changes under the same review rule as dependency changes.

For the related question of build logic you write yourself, see reviewing convention plugins and buildSrc.

Try it yourself

Click through it at your own pace, or open it full screen.

Step through the pull request and watch what a gate can flag when a version line changes.

Safeguard's policies and gates can block a pull request that changes dependencies against your rules, and the free scan at gold.safeguard.sh/scan shows what a repository pulls in.

Quick check

Sources

• Gradle: Plugin management and resolution
• Gradle: Declaring repositories

Last reviewed: 19 October 2026.