Spring Boot 4 Upgrade: OpenRewrite + Post-Migration Fixer

Upgrading to Spring Boot 4 is more than a version bump. Modular auto-configuration, Jackson 3, Spring Framework 7, Hibernate 7, and the new test-starter split break builds in ways the OpenRewrite recipe alone does not fix. This skill makes your coding agent work through the migration step by step, with checks along the way:

• Checks preconditions first: Boot 3.x, Java 17+, Gradle/Maven version, JDK compatibility, Java toolchain, Kotlin 2.2+, clean git tree, feature branch, green build.

• Fixes known bad patterns before the rewrite, so the recipe doesn't leave them half-migrated.

• Runs the official OpenRewrite Spring Boot 4.0 recipe. It uses a non-invasive Gradle init script (no build-file edits) or a one-line Maven command. It prefers the wrapper and handles Windows/PowerShell quoting.

• Pins OpenRewrite versions that resolve from Maven Central. Newer OpenRewrite releases are moving to an authenticated repository and fail with Could not find org.openrewrite:rewrite-bom. The skill avoids this and explains the fallback.

• Finds your internal libraries, corporate parent POMs, and convention plugins, and asks you for their Spring Boot 4–compatible versions. It never guesses.

• Includes a catalogue of 25+ real post-migration errors with before/after fixes, covering:

• o: modular starters (security, OAuth2, Kafka, Liquibase, WebMVC tests)

• o: Jackson 2 → 3 (customizers, serializationInclusion, visibility, JsonNullable)

• o: RestClient message converters

• o: HttpHeaders no longer being a Map

• o: @AutoConfigureObservability, Micrometer package moves

• o: TestRestTemplate, MockMvc, and WebTestClient annotations; @Mock fields no longer initialised

• o: Specification.unrestricted(), Hibernate 5 package removal

• o: the OpenAPI generator (the recipe's version bump is too old to work)

• o: OkHttp MockWebServer 3, Resilience4J in slice tests

• o: Undertow removal

• o: and more

• Catches what the recipe gets wrong: Spring Boot versions left on 3.x in Gradle version catalogs, stale version pins that override the Spring Cloud BOM, and hard-coded versions it adds.

• Runs your formatter after the rewrite (spring-javaformat, Spotless, ktlint), so formatter checks don't break the build.

• Optional second step from 4.0 to the latest 4.x release.

• Doesn't loop on slow builds: it stops and asks after two failed attempts on an unknown error.

• Never commits. It pauses at five checkpoints so you can review and commit each phase separately.

• Writes sb4-migration-report.md listing what changed, temporary measures to revert, remaining TODO-SB4 markers, new issues, and a suggested commit plan.

Tested end to end on six projects (Spring Boot 3.4/3.5 → 4.0.8), each ending with a green full build and all tests passing:

• spring-petclinic with Maven and with Gradle (Groovy DSL)
• spring-petclinic-rest (Maven, OpenAPI generator, Spring Security, Jackson customisation, 216 tests)
• spring-petclinic-microservices (Maven, 9 modules, Spring Cloud 2025.1, gateway, Resilience4J, OkHttp MockWebServer)
• spring-petclinic-kotlin (Kotlin 2.3, Gradle Kotlin DSL)
• a Gradle Kotlin DSL multi-module build with a version catalog and FAIL_ON_PROJECT_REPOS

It was also used by the author on internal production Gradle services. The catalogue's code fixes were also applied verbatim to a purpose-built project, then compiled and tested on Spring Boot 4. Where the maintainers of these projects had published their own Spring Boot 4 upgrade, the skill's result was compared with theirs. What it can't do for you: it can't guess compatible versions of your private/internal libraries (it asks), and very unusual setups may still need a human for a few errors. The skill stops and tells you instead of looping. Invoke it with /upgrade-spring-boot-4 or just ask your agent to "upgrade this project to Spring Boot 4". It changes nothing until it has checked the preconditions and you have said "continue". Licensing note: this skill uses the OpenRewrite rewrite-spring recipe. Your own build downloads the recipe under its own licence (Moderne Source Available License), and you run it on your own code. This skill contains no OpenRewrite or recipe code. Spring and Spring Boot are trademarks of Broadcom Inc. OpenRewrite is a trademark of Moderne, Inc. This skill is not affiliated with or endorsed by either.