Spring Boot 2.7 to 3.x Migration Checklist

Spring Boot 3 is not just another dependency bump. Use this checklist to estimate Java 17, Jakarta, Spring Security 6, Hibernate 6, dependency, and CI risks before you start changing code.

1. Confirm your current baseline

Capture your Spring Boot version, Java version, build tool, Spring Security style, Hibernate/JPA usage, servlet/JSP/JSTL usage, database drivers, CI JDK, and test coverage.

Spring Boot 3 requires Java 17+. If your project is still on Java 8 or 11, plan the Java migration before the Spring Boot version bump.

2. Move to Java 17+ first

update local JDK to 17 or 21
update CI runner JDK
update Maven/Gradle toolchain settings
run the full test suite before touching Spring Boot

./mvnw test
# or
./gradlew test

3. Scan for `javax.*` imports

Spring Boot 3 is based on Jakarta EE 10. Review javax.persistence.*, javax.validation.*, javax.servlet.*, javax.annotation.*, and JSP/JSTL tag libraries.

import javax.persistence.Entity;
// becomes
import jakarta.persistence.Entity;

4. Check Spring Security 5 → 6 changes

Look for WebSecurityConfigurerAdapter, authorizeRequests(), antMatchers(), and @EnableGlobalMethodSecurity. Prefer separate PRs for security configuration rewrites.

5. Review Hibernate 5 → 6 risks

Check custom dialects, native queries, JPQL/HQL, naming strategies, enum mappings, date/time mappings, lazy loading assumptions, and repository integration tests.

6. Check dependency compatibility

Area	Current	Target	Risk
Java	8/11	17/21	High
Spring Boot	2.7.x	3.x	High
Security	5.x	6.x	Medium/High
Hibernate	5.x	6.x	Medium/High

7. Split the migration into phases

Sprint 1: Java 17+ baseline
Sprint 2: Jakarta namespace migration
Sprint 3: major framework dependencies
Sprint 4: Spring Boot 3 upgrade validation

8. Generate migration tickets

Each ticket should include title, risk category, why it matters, affected evidence, suggested change, validation command, and rough effort.

9. Estimate before committing the team

If you cannot quickly answer how many javax.* imports exist, whether Java 17 is green, and which framework changes are risky, run a migration scan first.

Generate a free migration report

Spring Upgrade Radar scans a Spring Boot project locally and generates an executive summary, risk score, estimated roadmap, migration tickets, and Jira/GitHub export files.

spring-upgrade-radar scan /path/to/your/spring-project \
  --target 3.5 \
  --output out/report.md \
  --html-output out/report.html \
  --tickets-json out/tickets.json

View the project on GitHub →