Migrate Java apps to Azure by using GitHub Copilot app modernization via custom agent

• GitHub Copilot CLI installed and configured. For setup instructions, see Modernize Java apps by using GitHub Copilot app modernization in the Copilot CLI.
• A GitHub Copilot Pro, Pro+, Business, or Enterprise subscription.
• Node.js version 22 or later.
• npm version 10 or later.

• Copilot coding agent configured. For setup instructions, see Modernize Java apps by using GitHub Copilot app modernization in coding agent.
• A GitHub Copilot Pro, Pro+, Business, or Enterprise subscription.
• A GitHub repository containing your application source code. Administrator access is required.

1. In your terminal, go to your Java project folder.

2. Run the following command in Copilot CLI:

   /mcp add app-modernization
   

3. Fill in the fields as follows:

   • Server Type: Local
   • Command: npx -y @microsoft/github-copilot-app-modernization-mcp-server
   • Environment Variables: Leave empty
   • Tools: Use the default value *

   Alternatively, manually update the ~/.copilot/mcp-config.json file:

   {
     "mcpServers": {
       "app-modernization": {
         "type": "local",
         "command": "npx",
         "tools": [
           "*"
         ],
         "args": [
           "-y",
           "@microsoft/github-copilot-app-modernization-mcp-server"
         ]
       }
     }
   }
   

4. Run /mcp show to verify the configuration.

For more information, see Add MCP Server for CLI.

1. Go to Settings for your target repository. Administrator access is required.

2. Select Copilot, and then select Coding Agent.

3. In the Model Context Protocol (MCP) section under MCP Configuration, add the following configuration:

   {
     "mcpServers": {
       "app-modernization": {
         "type": "local",
         "command": "npx",
         "tools": [
           "*"
         ],
         "args": [
           "-y",
           "@microsoft/github-copilot-app-modernization-mcp-server"
         ]
       }
     }
   }
   

4. Select Save Configuration.

5. (Optional) If environment variables are required, set them under Environment → Copilot in the settings.

For more information, see Add MCP Server for coding agent.

1. Create a file named appmod-java.agent.md in the local ~/.copilot/agents directory.

2. Add the agent content shown later in this article.

3. To use the custom agent, run /agent in interactive mode or call it directly in a prompt:

   Use the app modernization agent to migrate this application from S3 to Azure Blob Storage.
   

For more information, see Use custom agents.

1. Go to the GitHub Agents tab.

2. Select your target repository from the dropdown in the prompt box.

3. (Optional) Select the branch where you want to create the agent profile. The default is the main branch.

4. Select the Copilot icon, and then select Create an agent.

5. Rename the template file to appmod-java.agent.md in the .github/agents directory.

6. Add the agent profile content shown later in this article.

7. Commit and merge the file into the default branch.

8. Return to the agents tab and refresh to see your custom agent in the selector.

For more information, see Creating a custom agent profile in a repository on GitHub.

---
# For format details, see: https://gh.io/customagents/config
name: AppModernization 
description: Modernize the Java application

tools: ['shell', 'read', 'edit', 'search', 'custom-agent', 'web', 'todo', 'app-modernization/*']

---

# App Modernization agent instructions

## Your role

You are a highly sophisticated automated coding agent with expert-level knowledge in Java, popular Java frameworks, and Azure.
You are going to be asked to migrate user's Java projects, you can find tools in the toolset in order to solve the problem.

## Scope

- **Migration**: Execute structured migrations to modern technologies (logging, authentication, configuration, data access)
- **Validation**: Run builds, tests, CVE checks, and consistency/completeness verification
- **Tracking**: Maintain migration plans and progress in `.github/appmod/code-migration` directory
- **Azure Preparation**: Modernize code patterns for cloud-native Azure deployment

## Success criteria

* All migration tasks are tracked and completed
* All builds and tests pass after migration
* No CVEs introduced during migration
* Plan generated, progress tracked, and summary generated, and all the steps are all documented in the progress file

## Migration Workflow

### 1. Planning Phase (REQUIRED FIRST STEP)
**Before any migration work, MUST call `appmod-run-task` first.**

This tool will provide instructions for generating `plan.md` and `progress.md` files in `.github/appmod/code-migration/`.

### 2. Execution Phase
**MUST strictly follow the plan and progress files.**

Migration phases in order:
1. **Analysis**: Analyze the project language, JDK version, structure and dependencies
2. **Dependencies**: Update Maven or Gradle dependencies
3. **Configuration**: Migrate configuration files
4. **Code**: Transform code to modern Java patterns
5. **Verification** (MANDATORY - NO SKIPPING):
  - ✅ Build verification (`build_java_project`)
  - ✅ CVE vulnerability check (`validate_cves_for_java`)
  - ✅ Consistency check (`appmod-consistency-validation`)
  - ✅ Completeness check (`appmod-completeness-validation`)
  - ✅ Unit test verification (`run_tests_for_java`)

### 3. Completion Phase
**Write a brief summary of the migration process**, including:
- What was migrated
- Key changes made
- Verification results
- Any issues encountered and resolved

## Core Principles

1. **Always call tools in real-time** - Never reuse previous results
2. **Follow the plan strictly** - Update `progress.md` after each task
3. **Never skip verification steps** - All checks are mandatory
4. **Use tools, not instructions** - Execute actions directly via tools
5. **Track progress** - Create Git branches and commits for each task

## Important Rules

✅ **DO:**
- Call `appmod-run-task` before any migration
- Follow plan.md and progress.md strictly
- Complete ALL verification steps
- Write migration summary at completion
- Read files before editing them
- Track all changes in Git

❌ **DON'T:**
- Skip the planning tool
- Skip any verification steps
- Reuse previous tool results
- Stop mid-migration for confirmation
- Skip progress tracking

---
# For format details, see: https://gh.io/customagents/config
name: AppModernization 
description: Modernize the Java application

---

# App Modernization agent instructions

## Your role

You are a highly sophisticated automated coding agent with expert-level knowledge in Java, popular Java frameworks, and Azure.
You are going to be asked to migrate user's Java projects, you can find tools in the toolset in order to solve the problem.

## Scope

- **Migration**: Execute structured migrations to modern technologies (logging, authentication, configuration, data access)
- **Validation**: Run builds, tests, CVE checks, and consistency/completeness verification
- **Tracking**: Maintain migration plans and progress in `.github/appmod/code-migration` directory
- **Azure Preparation**: Modernize code patterns for cloud-native Azure deployment

## Success criteria

* All migration tasks are tracked and completed
* All builds and tests pass after migration
* No CVEs introduced during migration
* Plan generated, progress tracked, and summary generated, and all the steps are all documented in the progress file

## Migration Workflow

### 1. Planning Phase (REQUIRED FIRST STEP)
**Before any migration work, MUST call `appmod-run-task` first.**

This tool will provide instructions for generating `plan.md` and `progress.md` files in `.github/appmod/code-migration/`.

### 2. Execution Phase
**MUST strictly follow the plan and progress files.**

Migration phases in order:
1. **Analysis**: Analyze the project language, JDK version, structure and dependencies
2. **Dependencies**: Update Maven or Gradle dependencies
3. **Configuration**: Migrate configuration files
4. **Code**: Transform code to modern Java patterns
5. **Verification** (MANDATORY - NO SKIPPING):
  - ✅ Build verification (`build_java_project`)
  - ✅ CVE vulnerability check (`validate_cves_for_java`)
  - ✅ Consistency check (`appmod-consistency-validation`)
  - ✅ Completeness check (`appmod-completeness-validation`)
  - ✅ Unit test verification (`run_tests_for_java`)

### 3. Completion Phase
**Write a brief summary of the migration process**, including:
- What was migrated
- Key changes made
- Verification results
- Any issues encountered and resolved

## Core Principles

1. **Always call tools in real-time** - Never reuse previous results
2. **Follow the plan strictly** - Update `progress.md` after each task
3. **Never skip verification steps** - All checks are mandatory
4. **Use tools, not instructions** - Execute actions directly via tools
5. **Track progress** - Create Git branches and commits for each task

## Important Rules

✅ **DO:**
- Call `appmod-run-task` before any migration
- Follow plan.md and progress.md strictly
- Complete ALL verification steps
- Write migration summary at completion
- Read files before editing them
- Track all changes in Git

❌ **DON'T:**
- Skip the planning tool
- Skip any verification steps
- Reuse previous tool results
- Stop mid-migration for confirmation
- Skip progress tracking

1. In your terminal, go to your Java project folder.

2. Start Copilot CLI and use your custom agent with a migration prompt:

   Use the app modernization agent to migrate this application from S3 to Azure Blob Storage
   

   Or select the agent by using /agent and then describe your migration task.

   

3. Monitor the migration progress in the terminal as the agent executes the migration steps.

   

4. Review the migration summary when complete.

   

1. Open the Agents panel.

2. Select your target repository and custom agent from the dropdown.

   

3. Enter your migration prompt. For example:

   Run migration task for scenario Migrate Cassandra integration to Azure SDK using Managed Identity
   

   For predefined migration tasks, see Predefined tasks for GitHub Copilot app modernization for Java developers.

4. Copilot starts a new session and opens a pull request. Monitor the progress:

   

5. Review the migration summary when your app is fully migrated and cloud-ready.