DEV Community

purewater02
purewater02

Posted on

Spring Boot 3 migration: I built a local CLI that generates risk estimates in minutes

#springboot #java #opensource #devtools

Spring Boot 3 migration: I built a local CLI that generates risk estimates in minutes

Spring Boot 3 is not just another dependency bump.

For many teams, the upgrade from Spring Boot 2.x to 3.x bundles several migrations at once:

  • Java 17+ baseline
  • javax.* → jakarta.* namespace migration
  • Spring Security 5 → 6 configuration changes
  • Hibernate 5 → 6 compatibility risks
  • dependency coordinate updates
  • CI/runtime surprises

The hard question usually comes before implementation:

What will break, how risky is it, and how many sprints should we reserve?

I built Spring Upgrade Radar as a local-first CLI and GitHub Action to answer that planning question.

What it does

Spring Upgrade Radar scans a Spring Boot Maven/Gradle project and generates:

  • Executive summary for CTOs, EMs, tech leads, and backend teams
  • Risk score and migration readiness grade
  • Top migration risks ranked by impact
  • Estimated sprint-by-sprint roadmap
  • Recommended migration backlog
  • Ticket exports for JSON, Jira CSV, and GitHub Issues Markdown
  • Markdown and HTML reports

The goal is not automatic rewriting. The goal is to give teams a practical first estimate before they start a migration project.

Why local-first matters

Your source code does not need to leave your machine.

Many teams cannot upload production code to a hosted SaaS scanner. Spring Upgrade Radar runs locally, in your own CI, or on a private runner. The default workflow generates a full report without uploading source code anywhere.

Why this helps before AI coding agents

Spring Upgrade Radar can also be used as a deterministic preflight step.

Instead of letting an LLM explore the codebase from scratch, run the CLI or GitHub Action first. The tool produces a risk map, estimated roadmap, and migration ticket backlog. That structured plan becomes the starting context for your coding agent, reducing token spend on repeated discovery and letting the LLMfocus on implementation and review.

GitHub Action usage

The v0.1.1 release is available as a free GitHub Action:

name: Spring Upgrade Radar

on:
  workflow_dispatch:
  pull_request:
    paths:
      - "**/pom.xml"
      - "**/build.gradle"
      - "**/*.java"

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - uses: purewater02/spring-upgrade-radar@v0.1.1
        with:
          project-path: "."
          target-version: "3.5"
          output-dir: "spring-upgrade-radar-output"
      - uses: actions/upload-artifact@v4
        with:
          name: spring-upgrade-radar-report
          path: spring-upgrade-radar-output/
Enter fullscreen mode Exit fullscreen mode

Local CLI quick start 

git clone https://github.com/purewater02/spring-upgrade-radar.git
cd spring-upgrade-radar
python3 -m venv .venv
. .venv/bin/activate
pip install -e .

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 \
  --jira-csv out/jira.csv \
  --github-issues-md out/github-issues.md
Enter fullscreen mode Exit fullscreen mode

Example output

A report starts with an executive summary like this:

# Executive Summary

- Spring Boot: 2.6.2 → 3.5
- Java: 8
- Risk score: 100/100 | Grade: C (Critical)

## Top 3 Risks
1. Spring Boot 2.x → 3.x major migration
2. Java 17 baseline gap
3. JPA javax.persistence imports

## Estimated Roadmap
- Sprint 1: Java 17+ build/runtime baseline — Estimated Time: 2 weeks
- Sprint 2: javax → jakarta namespace migration — Estimated Time: 2 weeks
- Sprint 3: dependency major upgrades — Estimated Time: 2 weeks
- Sprint 4: Spring Boot 3.x migration validation — Estimated Time: 1 week
Enter fullscreen mode Exit fullscreen mode

The full report includes evidence for each finding and exportable tickets for Jira and GitHub Issues.

Current check scope

v0.1.1 intentionally starts narrow. Current checks include:

  • Spring Boot 2.x → 3.x migration risk
  • Java baseline compatibility
  • Jakarta Persistence import migration (javax.persistence → jakarta.persistence)
  • Spring Security legacy configuration patterns
  • JSP/JSTL Jakarta compatibility risks
  • MySQL Connector/J coordinate migration
  • Wrapper and CI execution readiness

More checks will be added in later releases.

Links

Feedback wanted

This is an early v0.1.1 release. I am especially interested in feedback from teams that have already done, or are currently planning, Spring Boot 3 migrations.

Useful feedback would be:

  • Which migration risks are missing?
  • Which report sections are actually useful for planning?
  • Would your team use this in CI before starting an upgrade?
  • What output format would make adoption easier?

If you try it on a real project, please open a GitHub issue or discussion. Real-world migration edge cases are exactly what will make the next versions better.

Top comments (1)

Collapse
 
alexshev profile image
Alex Shev •

Risk estimates are a good fit for a local CLI because migration risk is so project-specific. The useful output is not just "this file is affected"; it is which ownership boundary, dependency, or runtime behavior makes the change dangerous.