Effortlessly Upgrade Your Spring Boot Application with GitHub Copilot's Custom Agent

Upgrading a Spring Boot application across major versions can be daunting. Breaking API changes, dependency incompatibilities, package reorganizations, and test failures can turn what should be a routine maintenance task into a multi-day ordeal. What if you could automate this entire process with a single command?

In this article, I'll show you how to use a custom GitHub Copilot agent to automatically upgrade a multi-module Spring Boot application from version 3.5.0 to 4.0.5, complete with dependency updates, code migrations, and test validations.

Prerequisites

Before we dive in, I'm assuming you:

• Have GitHub Copilot installed and activated in VS Code

• Are familiar with basic Copilot interactions (chat, inline suggestions)

• Understand what Spring Boot is and have worked with Maven projects

• Have a Spring Boot project that needs upgrading

If you're new to GitHub Copilot, check out the official documentation to get started.

What Are Custom Agents in GitHub Copilot?

GitHub Copilot Workspace introduces a powerful concept: custom agents. Think of them as specialized AI assistants with domain-specific expertise.

Understanding the Agent Hierarchy

Base Agent (GitHub Copilot)
Your primary AI coding assistant that handles general programming tasks, questions, and code generation.

Custom Agents
Specialized agents configured for specific tasks or domains. They extend Copilot's capabilities with:

• Domain-specific knowledge

• Predefined workflows

• Custom instructions and prompts

• Access to specialized tools

Sub-Agents
Purpose-built agents that work under a parent agent to handle specific subtasks. For complex operations, a custom agent might orchestrate multiple sub-agents, each handling a specific aspect of the task.

The Spring Boot Upgrader Agent Ecosystem

To address the complexity of Spring Boot upgrades, I built the Spring Boot Upgrader Agent—a purpose-built solution that transforms what used to be a multi-day manual task into an automated, reliable workflow. The agent is available as an open-source project at github.com/tanmoymandal/gh-copilot-agents.

The Spring Boot Upgrader is a parent agent that orchestrates several specialized sub-agents:

Sub-Agent	Purpose
SB Version Detector	Scans pom.xml/build.gradle to detect current Spring Boot, Java, and dependency versions
SB Docs Fetcher	Retrieves Spring Boot 4.0 release notes, migration guides, and ecosystem documentation
SB Dependency Upgrader	Updates all Spring Boot and related dependencies, handles Jakarta EE migrations, and resolves API removals
SB Test Updater	Fixes test compilation issues, updates deprecated test APIs, and runs the test suite
SB Vulnerability Scanner	Scans dependencies for CVEs before and after upgrade
SB Upgrade Reporter	Generates a comprehensive upgrade report document

This orchestrated approach ensures each aspect of the upgrade is handled by a specialized component, resulting in a thorough and reliable upgrade process.

Getting the Spring Boot Upgrader Agent

The Spring Boot Upgrader agent is available as an open-source project that you can easily integrate into your workspace.

Step 1: Clone the Agent Repository

git clone https://github.com/tanmoymandal/gh-copilot-agents.git
cd gh-copilot-agents

Step 2: Understand the Agent Configuration

The agent is configured using a .agent.md file with YAML frontmatter. Here's a simplified view of the structure:

---
name: Spring Boot Upgrade to 4.0.x
description: >
  Use when upgrading a Spring Boot project to version 4.0.x. 
  Orchestrates full upgrade workflow: version detection, Java version selection, 
  dependency upgrade, test updates, vulnerability scanning, and upgrade report generation.
applyTo:
  - filePattern: '**/pom.xml'
  - filePattern: '**/build.gradle*'
tools:
  - runSubagent
  - read_file
  - replace_string_in_file
  - run_in_terminal
---

# Agent Instructions

[Detailed workflow instructions for the agent...]

Key Configuration Elements:

• name: The identifier you'll use to invoke this agent

• description: What the agent does and when to use it

• applyTo: File patterns that trigger the agent's availability (Maven/Gradle files)

• tools: Which Copilot tools the agent can use

• Instructions: Detailed workflow steps the agent follows

Step 3: Install the Agent in Your Project

There are two ways to make the agent available:

Option A: Workspace-Level (Recommended for Team Projects)

Copy the .agent.md file to a .github/copilot/ directory in your project:

mkdir -p <your-project>/.github/copilot/agents
cp spring-boot-upgrade/.agent.md <your-project>/.github/copilot/agents/spring-boot-upgrader.agent.md

Option B: User-Level (Recommended for Personal Use)

Place the agent in your global Copilot configuration:

mkdir -p ~/.copilot/agents
cp spring-boot-upgrade/.agent.md ~/.copilot/agents/spring-boot-upgrader.agent.md

After copying, reload VS Code or restart the Copilot extension to make the agent available.

Real-World Example: Upgrading my-awesome-app

Let's walk through upgrading a real multi-module Spring Boot application. The my-awesome-app is a sample project available at https://github.com/tanmoymandal/my-awesome-app.

Project Structure

my-awesome-app/
├── pom.xml                    # Parent POM (Spring Boot 3.5.0)
├── dataaccess/                # Shared JPA entities and repositories
│   ├── pom.xml
│   └── src/main/java/...
├── api/                       # REST API module
│   ├── pom.xml
│   └── src/main/java/...
└── batch/                     # Spring Batch jobs
    ├── pom.xml
    └── src/main/java/...

Initial State

• Spring Boot: 3.5.0

• Java: 17

• Spring Batch: 5.2.2

• Spring Data JPA: 3.5.0

• Known Vulnerabilities: 16 CVEs (5 High, 6 Medium, 5 Low)

Step 1: Clone the Sample App

git clone https://github.com/tanmoymandal/my-awesome-app.git
cd my-awesome-app

Step 2: Open in VS Code

code .

Step 3: Invoke the Spring Boot Upgrader Agent

Open the GitHub Copilot Chat (Cmd+Shift+I on Mac, Ctrl+Shift+I on Windows/Linux) and type:

@Spring Boot Upgrade to 4.0.x upgrade this project to Spring Boot 4.0.x

Or simply:

Upgrade this Spring Boot project to version 4.0.x

If the agent is configured correctly with the applyTo patterns, it will automatically detect that you're in a Maven project and activate.

Step 4: Watch the Magic Happen

The agent will:

1. Detect Current Versions 🔍

   Analyzing pom.xml files...
   Detected: Spring Boot 3.5.0, Java 17
   

2. Fetch Migration Documentation 📖

   Retrieving Spring Boot 4.0 migration guide...
   Analyzing breaking changes...
   

3. Upgrade Dependencies ⬆️

   Updating parent POM to Spring Boot 4.0.5...
   Updating Spring Batch 5.2.2 → 6.0.3...
   Resolving starter modularization changes...
   

4. Apply Code Migrations 🔧

   Updating Spring Batch imports (package restructure)...
   Replacing deprecated APIs...
   

5. Update Tests

   Fixing test dependencies...
   Running test suite... 23/23 tests passed
   

6. Vulnerability Scan

   Pre-upgrade: 16 CVEs (5 High)
   Post-upgrade: 0 CVEs
   

7. Generate Report

   Creating UPGRADE_REPORT.md...
   

What Actually Changed?

1. Parent POM Update

 <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
-    <version>3.5.0</version>
+    <version>4.0.5</version>
     <relativePath/>
 </parent>

 <properties>
-    <java.version>17</java.version>
+    <java.version>25</java.version>
 </properties>

2. Starter Modularization (api/pom.xml)

Spring Boot 4.0 decomposed monolithic starters:

 <dependency>
     <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-web</artifactId>
+    <artifactId>spring-boot-starter-webmvc</artifactId>
 </dependency>

 <dependency>
     <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-test</artifactId>
+    <artifactId>spring-boot-starter-webmvc-test</artifactId>
     <scope>test</scope>
 </dependency>

+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-data-jpa-test</artifactId>
+    <scope>test</scope>
+</dependency>

3. Batch Module Updates (batch/pom.xml)

 <dependency>
     <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-batch</artifactId>
+    <artifactId>spring-boot-starter-batch-jdbc</artifactId>
 </dependency>

 <dependency>
-    <groupId>org.springframework.batch</groupId>
-    <artifactId>spring-batch-test</artifactId>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-batch-test</artifactId>
     <scope>test</scope>
 </dependency>

4. Spring Batch 6.0 Package Restructure

Spring Batch 6.0 reorganized core types into sub-packages:

-import org.springframework.batch.core.Job;
-import org.springframework.batch.core.Step;
+import org.springframework.batch.core.job.Job;
+import org.springframework.batch.core.step.Step;

-import org.springframework.batch.item.ItemProcessor;
-import org.springframework.batch.item.ItemWriter;
+import org.springframework.batch.infrastructure.item.ItemProcessor;
+import org.springframework.batch.infrastructure.item.ItemWriter;

-import org.springframework.batch.item.data.RepositoryItemReader;
-import org.springframework.batch.item.data.builder.RepositoryItemReaderBuilder;
+import org.springframework.batch.infrastructure.item.data.RepositoryItemReader;
+import org.springframework.batch.infrastructure.item.data.builder.RepositoryItemReaderBuilder;

These changes were applied automatically across:

• ProductReportJobConfig.java

• UserSyncJobConfig.java

• Both batch job test files

The Final Result

After the agent completes its work, you get:

✅ Fully Upgraded Application

• Spring Boot 3.5.0 → 4.0.5

• Java 17 → 25

• All dependencies updated to compatible versions

✅ Zero Vulnerabilities

• Eliminated all 16 CVEs (5 High, 6 Medium, 5 Low)

✅ All Tests Passing

• 23/23 tests pass with zero failures

• Test infrastructure updated to Spring Boot 4.0 conventions

✅ Comprehensive Documentation

• UPGRADE_REPORT.md with full change log

• Before/after comparison tables

• CVE remediation details

When to Use This Agent

The Spring Boot Upgrader agent is ideal for:

✅ Major Version Upgrades - Spring Boot 3.x to 4.x migrations
✅ Multi-Module Projects - Handles complex Maven/Gradle structures
✅ Security Compliance - Eliminates known CVEs through upgrades
✅ CI/CD Modernization - Part of dependency update automation
✅ Java Version Migrations - Coordinated Java + framework upgrades

⚠️ Important Considerations

While the agent is powerful, keep in mind:

1. Always Review Changes - The agent makes extensive modifications. Review all changes before committing.

2. Test Thoroughly - While the agent runs tests, you should perform additional integration and manual testing.

3. Backup First - Commit your current state or work in a branch before running the upgrade.

4. Custom Code - The agent handles framework migrations but can't understand all custom business logic. Manual review is required.

5. Version Compatibility - Ensure your application is compatible with Java 25 and Spring Boot 4.0's requirements.

Inspecting the Upgrade Report

The generated UPGRADE_REPORT.md contains:

## Executive Summary
- Before/after version matrix
- Dependency upgrade count
- Vulnerability remediation summary
- Test pass rates

## Version Changes
- Core framework versions
- Spring ecosystem dependencies
- Third-party library updates

## Migration Changes
- API breaking changes applied
- Package reorganizations
- Code transformations performed

## Test Results
- Module-by-module test results
- Failure details (if any)
- Coverage statistics

## Vulnerability Assessment
- Before/after CVE comparison
- Severity breakdown
- Remediation details

## Recommendations
- Post-upgrade tasks
- Performance considerations
- Further improvements
- Detected areas for enhancement (based on project analysis)

The agent intelligently analyzes your codebase during the upgrade process and may suggest areas for improvement—such as deprecated patterns it detected, opportunities for modernization, or performance optimizations that align with the new Spring Boot version's capabilities.

Next Steps

After a successful upgrade:

1. Review the changes carefully using git diff

2. Run your full test suite (unit, integration, E2E)

3. Test in a staging environment before production

4. Update your CI/CD pipelines for Java 25

5. Review and commit the UPGRADE_REPORT.md

Conclusion

Custom GitHub Copilot agents represent a paradigm shift in how we approach complex, repetitive development tasks. The Spring Boot Upgrader agent demonstrates how domain-specific AI assistants can handle tasks that typically require hours of manual work—dependency analysis, migration guide research, code transformations, testing, and documentation—all in a single automated workflow.

By leveraging sub-agents for specialized tasks and orchestrating them intelligently, we can achieve results that are both faster and more reliable than manual upgrades.

Try It Yourself

1. Clone the agent repository: gh-copilot-agents

2. Try the sample app: my-awesome-app

3. Follow instructions in this article to see how you can test out this agent against the sample app

Resources

• GitHub Copilot Documentation

• Spring Boot 4.0 Release Notes

• Spring Batch 6.0 Migration Guide

• Custom Agent Repository

• Sample Application

---

Have you used custom GitHub Copilot agents in your workflow? What tasks would you like to automate? Share your thoughts.

---