Spring Boot Upgrade Intelligence Agent

Overview

What It Does

Turns Spring Boot upgrades from uncertain migrations into planned, low-risk engineering work.

🔍

Collect

Scan repo facts

→

📰

Research

Fetch release notes

→

🧠

Analyze

GPT-5.2 reasoning

→

✅

Validate

Filter hallucinations

→

🔧

Fix

Auto-apply patches

→

🧪

Test

Generate stubs

🔍

Analyzes Your Codebase

Reads pom.xml, application.yml, and every .java file. Builds a complete inventory of your service — dependencies, plugins, config keys, imports, annotations, and code patterns.

📰

Researches Release Notes

Fetches 51 Spring Boot release notes, migration guides, config changelogs, and the full OpenRewrite recipe catalog. Prioritizes and trims to fit the context budget.

🧠

AI-Powered Reasoning

GPT-5.2 compares your repo inventory against all release notes. Identifies only the changes that directly apply to your specific service — not generic advice.

✅

Validates Every Finding

Cross-checks each LLM finding against actual code using 10 validation strategies. Hallucinations are filtered out. Only confirmed findings survive into the report.

🔧

Applies Automated Fixes

OpenRewrite handles deterministic code transforms. Maven bumps versions. The LLM fixes remaining compilation errors through iterative repair cycles.

🧪

Generates Test Stubs

Creates JUnit 5 test classes for identified coverage gaps — actuator endpoints, JWT auth, Jackson serialization, and observability integration tests.

Architecture

How the System Flows

Read left to right. Your repo goes in, a fully analyzed PR comes out. Click any phase for details.

Inputs

⚡

Trigger

PR change, weekly cron, or manual dispatch

📂

Your Repo

pom.xml, application.yml, every .java file

📰

Release Intel

42 release notes, 9 wiki guides, 9 recipes

Agent Pipeline — GitHub Actions Runner

SB Upgrade Agent

Java 25 CLI · 19 classes · Fat JAR (~5MB)

1

🔍

Collect

Scan repo into structured facts

2

📰

Research

Fetch 51 release documents

3

🧠

Analyze

GPT-5.2 finds impacts

4

✅

Validate

Filter hallucinations

5

🔧

Fix

OpenRewrite + LLM repair

6

🧪

Test

Generate JUnit stubs

External Services

🧠

Azure OpenAI

GPT-5.2 · ~50K tokens
Analysis + Fixes + Tests

🔄

OpenRewrite

9 Boot4 recipes
Deterministic transforms

📦

Maven Central

Version bumps
Parent + deps + props

📡

GitHub API

Release notes · Wiki
Issues · PRs · Push

Outputs

🔀

Pull Request

Version bumps, code fixes, generated tests

📋

GitHub Issue

7-section analysis report with evidence

📊

Markdown Report

docs/SPRING-BOOT-UPGRADE-REPORT.md

🖥️

Dashboard

Fleet-wide visibility (optional)

Inputs

Agent Core

AI / LLM

Outputs

External Services

Pipeline

Step-by-Step Flow

Click any step to expand its low-level implementation details.

0Detect Project Type

Checks for pom.xml or build.gradle to confirm this is a Spring Boot project

If no build file found → exits with code 0 (not a Spring Boot project).
Supports Maven (XML DOM parsing) and Gradle (regex extraction).
Multi-module projects: scans root and each submodule for build files.

1Collect Repo Facts

3 parallel collectors scan every aspect of the repository

BuildFileParser — SB version, Java version, all dependencies, plugins, properties, multi-module resolution

ConfigParser — application.yml flattened to dot-notation, actuator/kafka/DB/security config, secrets redacted

CodeScanner — walks every .java file, records imports/annotations/patterns → builds Map<pattern, List<FileLocation>>

2Fetch Release Intelligence

51 documents from 3 sources — release notes, wiki guides, recipe catalog

GitHub Releases API → 42 GA patch notes (filtered, skip milestones/RCs)

Wiki Clone → 9 pages: release notes + migration guides + config changelogs (asciidoc files in releasenotes/ subdir)

OpenRewrite Recipes → 9 hardcoded Boot4 recipes with names + descriptions

All merged, prioritized (migration guide first), trimmed to ~60K tokens context budget.

3GPT-5.2 AnalysisAI

Single API call — ~190K chars prompt, structured JSON response

System prompt: 15 categories to check, OpenRewrite recipe matching instructions

User prompt: RepoFacts + ReleaseNotes + Recipes + explicit checklist

Response schema:

{ riskLevel, findings[{id, severity, category, title, description, action, searchPattern, blastRadius, openRewriteRecipe}], upgradePlan[], testGaps[] }

Settings: temperature=0, response_format=json_object, ~50K tokens used

4Validate Findings

10 validation strategies cross-check against code, POM, and config

For each LLM finding, the searchPattern is checked against:

1. Code inventory (exact match)   2. Substring match   3. pom.xml dependencies
4. pom.xml plugins   5. pom.xml properties   6. application.yml config keys/values
7. Config subsections by blast radius   8. Regex match   9. Java version check
10. Repository URLs

Result: 14 CONFIRMED · 6 LIKELY · 5 FILTERED

5Generate Report & Deliver

7-section report delivered to Issue, Markdown file, and Dashboard

Report sections:
1. Upgrade Summary (risk badge, finding counts)
2. Breaking Changes (with file:line evidence)
3. Engineering Actions (grouped by category)
4. Runtime Risk (blast radius table)
5. OpenRewrite Auto-Fix ("9 of 20 auto-fixable" + Maven command + manual items)
6. Test Gaps
7. Upgrade Plan (step sequence)

Delivered to: GitHub Issue (create/update) · docs/SPRING-BOOT-UPGRADE-REPORT.md · Dashboard API POST

0Bump Java VersionSED

Updates java.version, maven.compiler.source/target in pom.xml

sed -i "s|<java.version>[0-9]*</java.version>|<java.version>25</java.version>|g" pom.xml

Also patches maven.compiler.source and maven.compiler.target properties.

1Bump Spring Boot ParentMaven

mvn versions:update-parent -DparentVersion=4.0.5

Updates <parent><version>4.0.3</version> → 4.0.5 in pom.xml.

2Bump Dependency PropertiesMaven

mvn versions:update-properties — bumps ALL *.version properties

Queries Maven Central for latest release of each property-referenced dependency:

confluent.version: 8.1.1 → 8.2.0
jackson-databind-nullable.version: 0.2.8 → 0.2.10
shared-kafka-utils-mvc.version: 1.0.3 → 1.0.4
testcontainers.version: 2.0.3 → 2.0.5

3Bump Direct DependenciesMaven

mvn versions:use-latest-releases — inline version bumps

Bumps inline dependency versions (not in properties). Skips snapshots, milestones, and RCs.

4OpenRewrite Auto-FixDeterministic

UpgradeSpringBoot_4_0 composite recipe — 9 sub-recipes

ReplaceMockBeanAndSpyBean → @MockBean → @MockitoBean
MigrateToModularStarters → starter renames
SpringBootProperties_4_0 → config property renames
AddAutoConfigureWebTestClient → test annotations
AddAutoConfigureTestRestTemplate → test annotations
RenameDeprecatedStartersManagedVersions
MigrateAutoConfigurePackages

5LLM Code FixerAI-Generated

Iteratively fixes what OpenRewrite couldn't — compile errors, Cucumber, complex patterns

1. mvn compile → captures remaining errors
2. For each error: reads file + error → sends to GPT → gets fix
3. Writes fix → re-compiles → repeats (max 3 iterations)
4. Also fixes manual findings from the report
5. Verifies build passes after all fixes

Guardrails: max 3 iterations, max 10 files/iteration, skips pom.xml/yml edits

6Generate Test StubsAI-Generated

4 test classes for identified coverage gaps

ActuatorContractUpgradeTest — health, liveness/readiness, Prometheus
OtlpObservabilityTest — OTLP trace export with new properties
JacksonCompatibilityTest — DTO serialization round-trips
JwtAuthUpgradeTest — JWT validation after Security 7

Written to src/test/java/.../generated/ · Uses JUnit 5 + Boot 4 patterns

7Create Pull Request

git branch → add → commit → push → gh pr create

Branch: spring-boot-upgrade/auto-fix-YYYYMMDDHHMMSS

git add -A captures ALL changes from phases 0–6
PR body lists all phases applied with ✅/⚠️ labels
Uses gh pr create (GitHub CLI, pre-installed on runners)
Auth: GITHUB_TOKEN (automatic)

Sequence

API Call Trace

Every external call the agent makes, in chronological order.

Agent	── GET →	GitHub API	/repos/spring-projects/spring-boot/releases?per_page=100
GitHub API	← 200 ──	Agent	42 GA release notes (JSON with markdown body)
Agent	── GIT →	GitHub Wiki	git clone --depth=1 spring-boot.wiki.git
Wiki	← clone ─	Agent	9 .asciidoc files (releasenotes/ subdir)
── prompt assembly ──
Agent	── POST →	Azure OpenAI	chat/completions (190K chars, temp=0, json_object)
GPT-5.2	← 200 ──	Agent	UpgradeAnalysis JSON (23 findings, 50K tokens)
── validation (local, no API calls) ──
Agent	── POST →	GitHub API	/repos/{repo}/issues — create upgrade report Issue
GitHub	← 201 ──	Agent	Issue #N created with 7-section report
── Job 2: Auto-fix ──
Runner	── EXEC →	Maven	versions:update-parent + update-properties + use-latest-releases
Maven	── GET →	Maven Central	Search latest versions for each property
Runner	── EXEC →	OpenRewrite	rewrite-maven-plugin:run (UpgradeSpringBoot_4_0)
Agent	── POST →	Azure OpenAI	chat/completions (code fix for each compile error)
Agent	── POST →	Azure OpenAI	chat/completions ×4 (test stub generation)
Runner	── PUSH →	GitHub	git push origin spring-boot-upgrade/auto-fix-*
Runner	── EXEC →	gh CLI	gh pr create --title "chore: Spring Boot upgrade"

Components

Agent Internals

12 Java classes + 7 data model records inside the agent JAR.

🎯

Agent.java

Main orchestrator. Runs all steps in sequence. Reads config from environment variables.

Entry pointCLI

📋

BuildFileParser

Parses pom.xml (XML DOM) + build.gradle (regex). Multi-module + property resolution.

javax.xmlMavenGradle

⚙️

ConfigParser

Parses YAML + properties. Flattens, redacts secrets, extracts structured config.

SnakeYAMLProperties

🔎

CodeScanner

Walks .java files line-by-line. Records imports, annotations, patterns → searchable inventory.

java.nioPattern match

📰

ReleaseNotesFetcher

GitHub API (42 notes) + Wiki clone (9 guides). Merge, prioritize, trim to context budget.

HttpClientGit clone

🔄

OpenRewriteRecipeFetcher

9 hardcoded Boot4 recipes. Generates the Maven command for execution.

OpenRewriteBoot4

🧠

LlmAnalyzer

Builds prompt, calls Azure OpenAI or Claude. Parses structured JSON response.

Azure OpenAIClaudeGPT-5.2

✅

FindingValidator

10 validation strategies. Checks code + pom + config. Filters hallucinations.

10 strategiesEvidence

📊

ReportGenerator

7-section Markdown + JSON output. OpenRewrite table. Risk badges.

MarkdownJSON

📤

OutputHandler

Delivers to: PR comment, Issue, Markdown file, Dashboard API.

GitHub APIREST

🔧

LlmCodeFixer

Post-OpenRewrite. Captures compile errors → LLM fix → re-compile. Max 3 iterations.

mvn compileFix loop

🧪

TestGenerator

LLM generates JUnit 5 test stubs for each test gap. Writes to generated/ package.

JUnit 5Boot 4

Data Models

Java Records

7 immutable data records that flow through the pipeline.

Record	Purpose	Key Fields
`ProjectDescriptor`	Build facts	sbVersion, javaVersion, dependencies[], plugins[], properties
`ConfigFacts`	Config facts	allProperties, actuator, kafka, datasource, security, profiles
`CodeFacts`	Code inventory	inventory Map, importSummary, annotationSummary
`ReleaseIntelligence`	Release notes	versionPath, mergedContent, releaseNotes[]
`UpgradeAnalysis`	Raw GPT response	riskLevel, findings[], upgradePlan[], testGaps[]
`ValidatedAnalysis`	After validation	findings[] (CONFIRMED/LIKELY only), evidence
`AgentConfig`	Runtime config	repoPath, targetVersion, outputModes, apiKeys

Connections

External Systems

Every external system the agent communicates with.

🧠 Azure OpenAI

POST chat/completions (analysis)
POST chat/completions (code fixes)
POST chat/completions (test gen)
Auth: api-key header
~50K tokens per scan

📡 GitHub API

GET releases (42 patch notes)
POST issues (create report)
PATCH issues (update existing)
POST issue comments (PR comment)
Auth: GITHUB_TOKEN

📚 GitHub Wiki

git clone spring-boot.wiki.git
9 asciidoc pages
releasenotes/ subdirectory
Shallow clone (depth=1)

📦 Maven Central

versions:update-parent
versions:update-properties
versions:use-latest-releases
Dependency resolution

🔄 OpenRewrite

rewrite-maven-plugin:run
rewrite-spring:LATEST
UpgradeSpringBoot_4_0
9 sub-recipes

🖥️ Dashboard

POST /api/v1/scans
X-API-Key auth
Spring Boot 3.5 + PostgreSQL
React + Vite frontend

Workflow

GitHub Actions Configuration

Trigger matrix and required secrets for the CI/CD pipeline.

Trigger Matrix

Trigger	Job 1 (Analysis)	Job 2 (Auto-Fix + PR)
PR with pom.xml change	✅ Creates Issue	⏭ Skipped
Weekly cron (Mon 2AM)	✅ Creates Issue	✅ Creates PR
Manual + auto-fix=false	✅ Creates Issue	⏭ Skipped
Manual + auto-fix=true	✅ Creates Issue	✅ Creates PR

Required Secrets

Secret	Source	Purpose
`AGENT_PAT`	Personal Access Token	Clone private sb-upgrade-agent repo
`OPENAI_API_KEY`	Azure OpenAI	GPT-5.2 API access
`AZURE_OPENAI_ENDPOINT`	Azure Portal	Resource URL
`AZURE_OPENAI_DEPLOYMENT`	Azure Portal	gpt-5.2
`AZURE_OPENAI_API_VERSION`	Azure Portal	2025-04-01-preview
`GITHUB_TOKEN`	Automatic	PRs, Issues, push

Stack

Technology

Everything that powers the agent, dashboard, and CI/CD pipeline.

🐳

Agent

Plain Java 25 CLI. No Spring framework. Fat JAR via Maven Shade plugin.

Java 25JacksonSnakeYAMLSLF4J

🖥️

Dashboard API

Spring Boot 3.5 + Spring Data JDBC + PostgreSQL database.

Spring Boot 3.5JDBCPostgreSQL

🎨

Dashboard UI

React + Vite + TypeScript + Tailwind CSS + Recharts.

ReactViteTailwindRecharts

🧠

AI / LLM

Azure OpenAI GPT-5.2. Also supports direct OpenAI + Claude APIs.

Azure OpenAIGPT-5.2Claude

🔄

Code Transform

OpenRewrite rewrite-spring plugin. Maven versions-maven-plugin.

OpenRewriteversions-plugin

⚡

CI/CD

GitHub Actions workflows. PAT for private repos. gh CLI for PR creation.

GitHub Actionsgh CLIPAT