skip to content

What is a Settings plugin in Gradle, and where do you apply one?

level: juniorimportance: must knowfreq 55%

answer

  1. Plugin<Settings> target
  2. plugins {} in settings.gradle.kts
  3. runs in initialization phase
  4. before projects configured
  5. develocity / foojay examples

basics

~10 s

A Settings plugin implements Plugin<Settings> and is applied in the plugins {} block of settings.gradle.kts. It runs during the settings phase, before any project is configured.

solid answer

~30 s

A Settings plugin is a Gradle plugin whose target type is the `Settings` object rather than `Project`. You apply it inside the `plugins {}` block at the top of `settings.gradle.kts` (after `pluginManagement {}`). Because settings is evaluated before the project graph is built, a Settings plugin can influence things that must be decided early: it can register/declare subprojects via `include(...)`, configure build features like Develocity build scans, register toolchain resolvers (foojay-resolver-convention), or wire dependency-resolution management. Common real examples are `com.gradle.develocity` and `org.gradle.toolchains.foojay-resolver-convention`. Contrast this with a Project plugin (applied in `build.gradle.kts`) which runs later, once each project is being configured.

code

kotlin · 8 lines
kotlin
// settings.gradle.kts
plugins {
    id("com.gradle.develocity") version "3.18"
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
}

rootProject.name = "my-app"
include("app", "core")

go deeper

for a junior

Know that it implements Plugin<Settings>, lives in the plugins {} block of settings.gradle.kts, and runs before projects.

for a middle

Explain the initialization-phase timing and give real examples (develocity, foojay) and what each enables.

for a senior

Contrast Settings vs Project vs Gradle plugin targets and articulate why build-wide concerns belong in settings.

for a principal

Discuss using Settings plugins (often as convention plugins published internally) to standardize toolchains, scans, and cache config org-wide.

## What a Settings plugin is Gradle has three lifecycle phases: **initialization**, **configuration**, and **execution**. The settings file (`settings.gradle.kts`) is evaluated during *initialization* — before any project's `build.gradle.kts` runs and before the project graph exists. A plugin in Gradle implements `Plugin<T>` where `T` is the object the plugin extends. The three common targets are: - `Plugin<Settings>` — applied in `settings.gradle.kts`, target is the `Settings` object. - `Plugin<Project>` — applied in `build.gradle.kts`, target is each `Project`. - `Plugin<Gradle>` — applied in init scripts, target is the `Gradle` build invocation. A **Settings plugin** therefore receives the `Settings` instance and can drive everything that has to be decided before projects exist. ## Where and how you apply it You apply it in the `plugins {}` block of `settings.gradle.kts`. That block must come **after** the optional `pluginManagement {}` block (which tells Gradle where to fetch plugins from): ```kotlin pluginManagement { repositories { gradlePluginPortal() } } plugins { id("com.gradle.develocity") version "3.18" id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" } rootProject.name = "my-app" include("app", "core") ``` ## Why the early timing matters Because it runs first, a Settings plugin can do things a Project plugin cannot do cleanly: - declare the set of subprojects (`include`, `includeBuild`), - configure **build-wide** features such as Develocity build scans / build cache, - register a **Java toolchain resolver** so toolchains can be auto-provisioned, - centralize dependency and version-catalog resolution via `dependencyResolutionManagement {}`. ## Common real Settings plugins - `com.gradle.develocity` — enables build scans, remote build cache, and predictive test selection across the whole build. - `org.gradle.toolchains.foojay-resolver-convention` — wires the foojay Disco API as a Java toolchain download repository. The key mental model: *project plugins shape one project; settings plugins shape the whole build, before projects exist.*

  • How does a Settings plugin differ from a Project plugin in terms of what it can do?
    A Settings plugin targets the `Settings` object and runs during initialization, so it can declare subprojects, configure build-wide features and toolchain resolvers. A Project plugin targets `Project`, runs during configuration, and shapes a single project.
  • Must the plugins {} block in settings come before or after pluginManagement {}?
    After. `pluginManagement {}` must be the first block because it defines where plugins are resolved from; `plugins {}` then applies them.

A Settings plugin is like a stage manager who arranges the set and the cast list before the curtain rises; a Project plugin is an actor who only acts once their scene begins.

saying these in an interview costs you the question

  • Saying Settings plugins go in build.gradle.kts — they go in settings.gradle.kts.
  • Claiming a Settings plugin can configure individual project tasks directly (projects don't exist yet).

context

resolving links…