Batch upgrade with the GitHub Copilot modernization agent

Batch upgrade enables you to apply consistent modernization plans across multiple repositories simultaneously. This article shows you how to upgrade multiple applications efficiently at enterprise scale.

By using batch upgrade, you can:

• Upgrade multiple applications simultaneously by using the same upgrade target.
• Apply consistent patterns by using similar upgrade patterns across applications.
• Leverage parallel execution when delegating to Cloud Coding Agents.

Batch upgrade provides the following benefits:

• Consistent execution:

  • Standardized approach: Apply the same modernization patterns across all repositories.
  • Reduced variability: Ensure consistent upgrade paths for similar applications.
  • Reusable strategies: Use organization-specific skills across applications.

• Scale and efficiency:

  • Parallel processing: Use Cloud Coding Agents to process multiple repositories simultaneously.
  • Automated workflows: Integrate with CI/CD pipelines for scheduled modernization.
  • Time savings: Reduce total modernization time from weeks to hours.

Prerequisites

• Modernize CLI.
• A completed batch assessment (recommended but not required).
• All repositories use the same programming language (Java or .NET).
• Access to all repositories you want to upgrade.
• GitHub authentication configured (gh auth login).

Configure repositories

The modernization agent supports multiple ways to specify the repositories you want to upgrade:

• Current folder: Upgrade the project in your current working directory.
• Manual input: Enter local directory paths or remote Git URLs directly.
• Repository config file: Use a JSON config file that lists all repositories.

Repository config file

For batch operations across many repositories, create a JSON config file to list all repositories. For example, create it at .github/modernize/repos.json in your working directory, or provide a custom path.

Simple format (array of repositories):

[
  {
    "name": "PhotoAlbum-Java",
    "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git"
  },
  {
    "name": "ZavaSocialFrontEnd",
    "url": "https://github.com/Azure-Samples/ZavaSocialFrontEnd"
  }
]

Full format (with branch and local paths):

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "local-project",
      "path": "/absolute/path/to/project"
    }
  ]
}

Each repo entry supports the following fields:

The modernization agent automatically detects the repos.json file at .github/modernize/repos.json when you select From a config file in interactive mode. You can also provide a custom path.

Choose your execution mode

Batch upgrade supports two execution modes and two interaction methods:

Execution modes

Local execution

• Best for: Testing, smaller sets of repositories (1-5 repos), or when you prefer local control.
• How it works: Processes repositories sequentially on your local machine.
• Setup required: None beyond the basic prerequisites.
• Supports: Both Git URL and local path repositories.

Cloud Coding Agent delegation

• Best for: Enterprise-scale operations, large portfolios (5+ repos), or parallel processing.
• How it works: Submits tasks to GitHub Cloud Coding Agents for parallel execution in the cloud.
• Setup required: MCP server configuration in each repository (configured during setup).
• Supports: Only repositories with GitHub (github.com) URLs. Local paths and non-GitHub providers aren't supported.

Interaction methods

Interactive mode (TUI)

• Guided experience with menus and prompts.
• Best for first-time users or when you want to review options.
• Supports both local and cloud execution.

Non-interactive mode (CLI/headless)

• Command-line based, fully automated.
• Best for CI/CD pipelines and automation.
• Supports both local and cloud execution with --delegate cloud flag.

How batch upgrade works

The batch upgrade workflow:

1. Language detection: Automatically detects the project language (Java or .NET) from the first repository.
2. Plan creation: Creates an upgrade plan based on your prompt or uses latest LTS versions.
3. Execution: Applies the upgrade to each repository.
4. Validation: Builds and validates changes for each repository.

Run batch upgrade

After you configure your repositories and choose an execution mode, start the batch upgrade.

Interactive mode (upgrade locally)

1. Run the modernization agent:

   modernize
   

2. Select Upgrade from the main menu.

   

3. Choose how to specify your target repositories. Select From a config file to use a repos.json file.

   

   Tip

   You can also select Manual input to enter local paths or remote Git URLs directly, or Current folder to upgrade the project in your current directory.

4. If the repos.json file is detected at the default location, the agent automatically fills it in. Otherwise, enter the path to your config file and press Enter.

5. All repositories are selected by default. Deselect any repositories you want to skip, and then press Enter to confirm your selection.

   • Use arrow keys to navigate and press Space to toggle individual repositories.

   

6. Choose the execution mode. Select Upgrade locally.

   

7. Enter the upgrade target prompt (for example, Java 21 or .NET 10) or press Enter to accept the default (latest LTS version).

8. The agent automatically:

   • Creates an upgrade plan based on your request.
   • Applies the plan to each repository sequentially.
   • Builds and validates each repository after changes.
   • Displays progress and summary for each repository.

   

Interactive mode (delegating to Cloud Coding Agents)

Prerequisites: Configure MCP server

Before running the upgrade, configure the GitHub Copilot Modernization MCP Server in each repository.

For Java applications, add this configuration in the Cloud Coding Agent section of your repository settings:

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

Steps

1. Run the modernization agent:

   modernize
   

2. Select Upgrade from the main menu.

   

3. Choose how to specify your target repositories. Select From a config file.

   

4. If the repos.json file is detected at the default location, the agent automatically fills it in. Otherwise, enter the path to your config file and press Enter.

5. All repositories are selected by default. Deselect any repositories you want to skip, and then press Enter to confirm your selection. Use arrow keys to navigate and press Space to toggle individual repositories.

   

6. Choose the execution mode. Select Delegate to Cloud Agents.

   

7. Enter the upgrade target prompt (for example, Java 21) or press Enter to accept the default.

8. The agent automatically:

   • Creates upgrade plans for each repository.

   • Submits a Cloud Coding Agent job for each repository.

   • Runs jobs independently in parallel in the cloud.

   • Displays job IDs and PR URLs for each repository.

     

   • Delegates tasks to AgentHQ for parallel execution.

     

   • Tracks progress for each individual task in real-time.

     

   • Displays upgrade summary for each completed task.

     

Non-interactive mode (CLI)

For automation and CI/CD integration, use the modernize upgrade command:

Upgrade locally using a repository config file:

modernize upgrade "Java 21" --source .github/modernize/repos.json

Upgrade multiple repositories by specifying sources directly:

modernize upgrade "Java 21" --source https://github.com/org/repo1 --source https://github.com/org/repo2

Upgrade using Cloud Coding Agents:

modernize upgrade "Java 21" --source .github/modernize/repos.json --delegate cloud

Review results

When the batch upgrade finishes:

1. Check the aggregated report displayed in the terminal.

2. Review individual repository changes:

   cd <repository-name>
   git status
   git diff
   

3. Create pull requests for successful upgrades:

   cd <repository-name>
   gh pr create --title "Upgrade to Java 21" --body "Automated upgrade by modernization agent"
   

Troubleshooting batch upgrades

Common problems

Repository access errors:

• Verify GitHub authentication by using gh auth status.
• Make sure you have access to all repositories in repos.json.

Language mismatch errors:

• Make sure all repositories in repos.json use the same language (Java or .NET).
• Create separate batch operations for different languages.

Clone failures:

• Verify repository URLs in repos.json are correct and accessible.
• Make sure you have proper access permissions to all repositories.
• Check network connectivity and VPN settings.

Build failures after upgrade:

• Review build error messages in the aggregated report.
• Check if you need to update other dependencies.
• Verify compatibility of third-party libraries with the new version.

Individual repository failures:

• The batch process continues even if individual repositories fail.
• Review the aggregated report to identify failed repositories.
• Check error logs for specific error messages.
• Retry failed repositories individually.

Cloud Coding Agent failures:

• Check GitHub Actions permissions and quota limits.
• For .NET Framework, make sure Windows runner configuration is properly set.

Next steps

After completing batch upgrade, you can:

Continue improving:

• Run batch assessment - Reassess to verify improvements and identify new opportunities.
• Create custom skills for organization-specific patterns - Capture successful patterns for reuse.

Learn more:

• Learn about CLI commands

Provide feedback

We value your input! If you have any feedback about batch upgrade or the Modernization agent, create an issue at the github-copilot-appmod repository or use the GitHub Copilot modernization feedback form.