Quickstart: Upgrade a Java project with GitHub Copilot modernization

GitHub Copilot modernization provides an AI-powered agentic experience that automates Java upgrade workflows end-to-end - from project analysis and plan generation to code transformation, build validation, and CVE remediation.

Supported upgrade scenarios

Upgrade Java Development Kit (JDK) to Java 11, 17, 21, or 25.
Upgrade Spring Boot up to version 4.0.
Upgrade Spring Framework up to version 7.x.
Upgrade Java EE to Jakarta EE, up to Jakarta EE 11.
Upgrade Azure SDK for Java.
Upgrade JUnit.
Upgrade third-party dependencies to a specified version.

Prerequisites

A GitHub account with GitHub Copilot enabled. You need a Free Tier, Pro, Pro+, Business, or Enterprise plan.
Java JDK for both the source and target JDK versions.
Maven or Gradle to build Java projects.
A Git-managed Java project using Maven or Gradle.
For Maven-based projects: access to the public Maven Central repository.

The latest version of Visual Studio Code.
GitHub Copilot in Visual Studio Code. For setup instructions, see Set up GitHub Copilot in Visual Studio Code. Be sure to sign in to your GitHub account within Visual Studio Code.
GitHub Copilot modernization. Restart Visual Studio Code after installation.

The latest version of IntelliJ IDEA.
GitHub Copilot. For more instructions, see Set up GitHub Copilot in IntelliJ IDEA. Be sure to sign in to your GitHub account within IntelliJ IDEA.
GitHub Copilot modernization. Restart IntelliJ IDEA after installation. If you don't have GitHub Copilot installed, you can install GitHub Copilot modernization directly.
For more efficient use of GitHub Copilot modernization: in the IntelliJ IDEA settings, select the Tools > GitHub Copilot configuration window, and then select Auto-approve and Trust MCP Tool Annotations. For more information, see Configure settings for GitHub Copilot modernization to optimize the experience for IntelliJ.

Install the GitHub Copilot CLI:
```
npm install -g @github/copilot
```

Install the GitHub Copilot modernization plugin:

copilot plugin marketplace add microsoft/modernize-java
copilot plugin install modernize-java@modernize-java

Note

An Azure account is required only for deploying resources to Azure, and isn't needed when using GitHub Copilot modernization to make code changes.

If you're using Gradle, only the Gradle wrapper version 5 or later is supported.

The Kotlin Domain Specific Language (DSL) isn't supported.

Select a Java project to upgrade

For this tutorial, choose one of the following sample repositories:

Maven: uportal-messaging
Gradle: docraptor-java

Launch the upgrade

Use the following steps to start the upgrade process:

Open the selected Java project in Visual Studio Code.
In the sidebar, open the GitHub Copilot modernization panel to see the QuickStart page.
Select Upgrade Java Runtime & Frameworks.

This action opens GitHub Copilot Chat in agent mode and automatically starts the upgrade process.

Tip

You can also select a specific task from the Tasks tree below the QuickStart panel (for example, Upgrade Spring Boot Version or Upgrade Jakarta EE Version) to trigger a targeted upgrade.

Alternatively, you can type directly in GitHub Copilot Chat using agent mode - for example, "Upgrade my Java project to Java 21" - to start the upgrade.

Use the following steps to start the upgrade process:

Open the selected Java project in IntelliJ IDEA.
In the sidebar, open the GitHub Copilot modernization panel to see the QuickStart page.
Select Upgrade Runtime & Frameworks.

This action opens GitHub Copilot Chat in agent mode and automatically starts the upgrade process.

Tip

You can also type directly in GitHub Copilot Chat using agent mode - for example, "Upgrade my Java project to Java 21" - to start the upgrade.

Use the following steps to start the upgrade process:

Open a terminal and navigate to your Java project directory.

Run the upgrade command:

copilot --model claude-sonnet-4.6 --agent modernize-java:modernize-java

After the agent starts, type your upgrade request:
```
upgrade to Java 21 + Spring Boot 3.5.x
```

Select upgrade targets

After you start the upgrade, the agent prompts you to select your target versions. Choose the desired Java version and, if applicable, the Spring Boot version for your project.

Review and edit the upgrade plan

GitHub Copilot modernization analyzes the Java project in the current workspace, including its JDK, build tools, and dependencies. The tool generates a plan.md file that includes:

Available Tools — detected JDKs and build tools in your environment.
Guidelines — user-specified constraints for the upgrade process.
Options — working branch and test configuration.
Upgrade Goals — source and target versions for each component.
Technology Stack — dependency compatibility analysis with incompatibility reasons.
Derived Upgrades — additional upgrades required by the primary targets (for example, javax → jakarta namespace migration when upgrading to Spring Boot 3.x).
Impact Analysis — detailed breakdown of dependency changes, source code changes, configuration changes, CI/CD changes, and risks.
Upgrade Steps — ordered migration steps with rationale and verification criteria.

Review the plan and make changes if needed, then confirm to proceed. For information about further customization, see Customize the upgrade plan.

Tip

Ensure that the plan matches your desired upgrade targets - for example, Java 8 to Java 21, Spring Boot 1.5 to 3.5.

Execute the upgrade

After you confirm the plan, the agent automatically proceeds with the code transformation phase. As part of this process, it performs the following tasks:

Modifies code and configuration files to ensure compatibility with the target versions.
Performs build validation to confirm the project compiles successfully at each step.
Executes test validation if enabled in the plan options.

The agent iterates through each upgrade step until all steps complete successfully. You can monitor progress at any time by checking the progress.md file in the editor.

CVE validation and fix

After the code transformation steps complete, the agent automatically scans dependencies for Common Vulnerabilities and Exposures (CVE) issues. If CVEs are found, the agent fixes them by upgrading the affected dependencies - no manual intervention is required. The final validation step then runs to confirm everything still builds and passes tests after the CVE fixes.

View the summary

After the upgrade, the tool generates a summary.md file, which includes:

Executive Summary — a one-paragraph overview of what was upgraded and the outcome.
Upgrade Improvements — a before/after comparison table with key benefits.
Build and Validation — build status and test results.
Limitations — any unfixable issues remaining after the upgrade.
Recommended next steps — suggested follow-up actions such as generating unit tests or addressing any remaining unfixed CVEs.
Additional details — project metadata, code changes, and CVE scan results.