Gradle Plugin Architecture

Relevant source files

• buildSrc/src/main/java/org/springframework/boot/build/KotlinConventions.java
• buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java
• config/detekt/config.yml

This page describes the internal architecture of the Spring Boot Gradle plugin, located at spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/. It covers the plugin entry point, the PluginApplicationAction pattern, each individual plugin action, the core tasks, the dependency management DSL surface, and the test infrastructure used to verify the plugin across Gradle versions.

For information about the Maven plugin, see 3.2. For an overview of how the Gradle plugin fits alongside the Maven plugin and the buildpack platform library, see 3.

---

Plugin Entry Point

SpringBootPlugin is the single class that Gradle instantiates when the org.springframework.boot plugin id is applied. Its responsibilities are:

1. Register the SpringBootExtension on the target project.
2. Iterate over all registered PluginApplicationAction instances and attach each as a "plugin applied" listener.
3. Apply a set of unconditional configuration (e.g., creating the bootJar / bootWar / bootRun tasks on the appropriate project type).

All plugin-specific customization is deferred through the PluginApplicationAction pattern rather than executed eagerly in apply().

Diagram: Plugin bootstrap sequence

Sources: spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/SpringBootPlugin.java

---

The PluginApplicationAction Pattern

PluginApplicationAction is a single-method interface:

interface PluginApplicationAction {
    String getPluginId();
    void execute(Project project);
}

SpringBootPlugin iterates its list of actions and calls project.getPluginManager().withPlugin(action.getPluginId(), p -> action.execute(project)). This ensures that each action is applied only if its corresponding ecosystem plugin is present, and it fires in the correct order regardless of when the user applies that plugin.

Diagram: PluginApplicationAction implementations and their trigger plugin IDs

Sources: spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/PluginApplicationAction.java, spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/SpringBootPlugin.java

---

Individual Plugin Actions

JavaPluginAction

The most consequential action. When the java plugin is present, it:

• Registers the bootJar task (type BootJar), wired to the main source set's runtime classpath.
• Registers the bootRun task (type BootRun), configured to use the main source set.
• Disables the plain jar task by default (so bootJar becomes the primary artifact) unless the user explicitly re-enables it.
• Configures ResolveMainClassName to find the application entry point.

WarPluginAction

When the war plugin is present:

• Registers bootWar (type BootWar).
• Disables the plain war task by default.
• Wires the bootWar artifact into the default configuration.

ApplicationPluginAction

When the application plugin is present, synchronizes mainClass between the Spring Boot extension and the standard application extension so both are kept consistent.

KotlinPluginAction

When org.jetbrains.kotlin.jvm is present:

• Configures the bootRun task's JVM arguments to include the Kotlin-specific kotlinOptions.
• Ensures the Kotlin compiler uses the correct JVM target consistent with the project's Java toolchain.

Note: KotlinPluginAction inside the Gradle plugin is separate from KotlinConventions in buildSrc. The former configures user projects; the latter configures how the Spring Boot repository itself is built. See 2.2 and 5.2 for the buildSrc conventions.

NativeImagePluginAction

When org.graalvm.buildtools.native is present:

• Configures the native image compilation task to use the correct main class name resolved by ResolveMainClassName.
• Wires the processAot and processTestAot tasks into the native compilation inputs.

CycloneDxPluginAction

When org.cyclonedx.bom is present:

• Configures the CycloneDX SBOM task to use the correct artifact coordinates from the Spring Boot extension.

DependencyManagementPluginAction

When io.spring.dependency-management is present:

• Imports the Spring Boot BOM (spring-boot-dependencies) as a managed platform, so users get curated dependency versions automatically without specifying version numbers.

MavenPluginAction

When maven-publish is present:

• Customizes the generated POM to align with Spring Boot artifact metadata conventions.

---

Core Tasks

Task class	Gradle task name	Purpose
BootJar	bootJar	Produces an executable fat JAR with the loader prepended
BootWar	bootWar	Produces an executable fat WAR
BootRun	bootRun	Runs the application in-process via Gradle
BootBuildImage	bootBuildImage	Builds an OCI image using Cloud Native Buildpacks
ResolveMainClassName	resolveMainClassName	Scans the classpath to find the @SpringBootApplication entry point

BootJar and BootWar

Both extend Gradle's standard Jar/War task types. They place the application classes in BOOT-INF/classes/ and all dependency JARs in BOOT-INF/lib/, then prepend the spring-boot-loader classes at the root of the archive. This layout is what allows JarLauncher / WarLauncher to find and launch the application.

Key configured properties:

• mainClass — resolved from ResolveMainClassName or overridden in the DSL.
• layered — enables the layered JAR layout for optimized Docker image caching.
• requiresUnpack — marks specific JARs that must be unpacked before execution.

BootRun

Extends JavaExec. Configured automatically to use the main source set classpath, making IDE-like run behavior available from the command line. The bootRun task does not produce an artifact.

BootBuildImage

BootBuildImage delegates to the spring-boot-buildpack-platform library (see 3) to invoke the Cloud Native Buildpacks lifecycle. Key DSL properties:

Property	Description
imageName	Target OCI image name
builder	Buildpack builder image
runImage	Runtime base image
environment	Environment variables passed to the build
publish	Whether to push the image to a registry
docker	Docker daemon connection settings
buildpacks	List of buildpacks to use instead of the builder's defaults
bindings	Volume bindings for the build container
tags	Additional tags to apply to the built image

Diagram: BootBuildImage task relationships

Sources: spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.java

---

Dependency Management DSL

The SpringBootExtension exposes a small DSL on the project under the springBoot {} block:

buildInfo() registers a BuildInfo task that writes build metadata (project group, artifact, version, time) into META-INF/build-info.properties inside the archive, making it available to BuildInfoAutoConfiguration at runtime.

The DependencyManagementPluginAction handles automatic BOM import when the io.spring.dependency-management plugin is on the classpath, importing org.springframework.boot:spring-boot-dependencies at the current Spring Boot version.

---

Testing Infrastructure

The Gradle plugin module has a dedicated test infrastructure to verify plugin behavior across multiple Gradle versions.

GradleCompatibilityExtension

A JUnit 5 ParameterizedExtension (registered as @GradleCompatibility on test classes). It:

1. Reads the list of supported Gradle versions from a resource file.
2. Creates a parameterized test invocation for each version.
3. Injects the current Gradle version into the GradleBuild field on the test instance before each test method runs.

This ensures a single test class exercises the plugin against every supported Gradle version without manual duplication.

GradleBuild

A JUnit 5 @RegisterExtension-compatible helper that:

• Sets up a temporary project directory with a settings.gradle and build.gradle for each test.
• Runs the Gradle build using GradleRunner from the Gradle TestKit, pointed at a specific Gradle version.
• Provides convenience methods (build(String... tasks), buildAndFail(String... tasks)) that return the BuildResult for assertion.

Diagram: Test kit execution flow

Sources: spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/junit/GradleCompatibilityExtension.java, spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/testkit/GradleBuild.java

---

Architectural Summary

Sources: spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/SpringBootPlugin.java, spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/