Batch assessment with the GitHub Copilot modernization agent

Batch assessment enables you to analyze multiple applications simultaneously, providing a comprehensive view of the modernization landscape across your applications. This article guides you through the process of assessing multiple repositories efficiently.

Batch assessment is especially valuable for migration planning because it enables you to efficiently assess the readiness and requirements of various applications at once. By using batch assessment, you can evaluate different repositories at the same time and obtain detailed assessment reports for each application. It produces two kinds of reports to support your migration planning:

• Per app report: Provides detailed insights into all modernization problems identified at the individual repository level.
• Aggregated report: Presents an overall perspective of all assessed applications, offering summary insights, recommendations on Azure services, target platforms, and upgrade paths. Additionally, the aggregated report includes shortcuts for easy access to each per app report.

Batch assessment provides the following benefits:

• Cross-applications visibility:

  • Aggregated reports: Get a comprehensive view across applications.
  • Cross-repository analysis: Identify common patterns and dependencies across applications.
  • Prioritization insights: Understand which applications need immediate attention.

• Scale and efficiency:

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

Prerequisites

• Modernize CLI.
• Access to all repositories you want to assess.
• GitHub authentication is configured (gh auth login).

Configure repositories

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

• Current folder: Assess 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.

Make sure you have the right permissions for the repositories or fork them.

Simple format (array of repositories):

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

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:

Full format with app grouping (optional, for organized reporting):

You can add an apps[] section to group repositories into logical applications. When apps are defined, the aggregated report organizes results by application and supports report distribution to external destinations.

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "PhotoAlbum",
      "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
    }
  ],
  "apps": [
    {
      "identifier": "photo-app",
      "description": "Photo management application",
      "repos": ["PhotoAlbum-Java"],
      "output": {
        "type": "local",
        "path": "/path/to/reports/photo-app"
      }
    }
  ]
}

Each app entry supports:

The output field supports the following distribution types:

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.

Run batch assessment

Two execution modes are available:

• Local execution: The modernization agent processes repositories one after another on your local machine. This mode works best for a smaller set of applications or for initial testing. Supports both Git URL and local path repositories.
• Cloud Coding Agent delegation: The modernization agent submits tasks to GitHub Cloud Coding Agents for parallel processing in the cloud. This mode is faster for multi-repo scenarios.

Interactive mode (assess locally)

1. Run the modernization agent:

   modernize
   

2. Select Assess 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 assess 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 Assess locally.

   

7. Select the assessment domains to analyze. Choose from Java upgrade and Cloud Readiness, and then press Enter.

   

8. Review and configure the assessment options. The configuration page shows options grouped by language and domain:

   • Java / GENERAL: Analysis Coverage (Issue only, Issues & Technologies, or Issues, Technologies & Dependencies).
   • Java / JAVA UPGRADE: Target Runtime (OpenJDK 11, 17, or 21).
   • Java / CLOUD READINESS: Target Compute Services, Target Operating System, and Containerization.
   • .NET / CLOUD READINESS: Target Compute Services.

   Use the arrow keys to navigate, press Enter to change a value, or select Continue to proceed with the current settings.

   

   Tip

   The recommended defaults work for most scenarios. You only need to change these settings if you have specific requirements, such as targeting a particular JDK version or Azure compute service.

9. Enter the output path for assessment results or press Enter to accept the default.

10. The agent automatically:

    • Clones remote repositories (local path repositories are used directly).

    • Runs assessment on each repository one by one.

    • Generates individual assessment reports.

      

    • Creates an aggregated report.

      

11. When the assessment finishes, the agent automatically opens the aggregated report.

    

Interactive mode (delegating to Cloud Coding Agents)

First, configure Cloud Coding Agents in each application repository. To configure Cloud Coding Agents, fork the sample repositories.

Configuration for .NET applications

Configure to run on Windows for .NET Framework applications

By default, the Copilot Coding Agent runs in an Ubuntu Linux environment. For .NET Framework applications, you need a Windows environment. To enable it, configure .github/workflows/copilot-setup-steps.yaml in the main branch of your application repository as shown in the following example:

# Windows-based Copilot Setup Steps for .NET tasks
# Note: Windows runners have firewall limitations that may affect some network operations
# Use this workflow for .NET projects that require Windows-specific tooling

name: "Copilot Setup Step (Windows)"

on:
  workflow_dispatch:

jobs:
  copilot-setup-steps:
    runs-on: windows-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

Learn more from: Customizing Copilot's development environment with Copilot setup steps

Disable firewall

Disable Copilot coding agent's integrated firewall in your repository settings as shown in the following image:

Configuration for Java applications

Configure GitHub Copilot Modernization MCP Server in Cloud Coding Agent section of your repository settings as shown in the following example:

{
  "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 Assess from the main menu.

   

3. Choose how to specify your target repositories. Select From a config file to use a repos.json file, or select Manual input to enter GitHub repository URLs directly.

   

4. If you selected From a config file and 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.

   

   Note

   When you delegate to Cloud Coding Agents, the domain selection and assessment configuration steps aren't supported. The cloud agent uses the default configurations to run assessment.

7. Enter the output path for assessment results or press Enter to accept the default.

8. The agent automatically delegates assessment tasks for each repository to Cloud Coding Agents and executes them in the cloud in parallel.

   

   The agent pulls the per-app assessment results back to local and generates the aggregated report locally.

   

9. When the assessment finishes, the agent automatically opens the aggregated report.

Non-interactive mode (CLI)

You can also use non-interactive mode by specifying command arguments directly. Use the modernize assess command:

Assess locally using a repository config file:

modernize assess --source .github/modernize/repos.json

Assess multiple repositories by specifying sources directly:

modernize assess --source https://github.com/org/repo1 --source https://github.com/org/repo2

Assess by delegating to Cloud Coding Agents:

modernize assess --source .github/modernize/repos.json --delegate cloud --wait

For more information, see assess - CLI commands.

Understanding the aggregated report

The aggregated report provides a comprehensive view across assessed applications as follows:

Dashboard

• Snapshot of portfolio health: total apps, how many need upgrades, and aggregate blocker and issue counts.
• Technology distribution: what frameworks are in use and how many apps share them.
• Effort distribution: whether the overall migration is a small or large undertaking.

Recommendations

• Azure Services: maps current dependencies to recommended Azure equivalents. Shared dependencies across apps are decided once, so you avoid per-app rework.
• Target Platform: guides hosting choice, such as Azure Container Apps versus AKS, and surfaces consolidation opportunities.
• Upgrade Path: identifies which apps need framework upgrades as a prerequisite, separating upgrade work from migration work.
• Migration Waves: sequences apps by readiness and risk into phases. This approach enables early wins while harder apps are prepared in parallel.

Application Assessment Matrix

• Quick overview for each application on aspects of framework, target platform, upgrade recommendation, issue breakdown (Mandatory, Potential, Optional), effort sizing, and more.
• Links to individual app reports for drill-down when needed.

Troubleshooting batch assessment

Common problems

Repository access errors:

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

Clone failures:

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

Assessment failures:

• Check if the repository contains valid Java or .NET projects.
• Verify that build files exist, such as pom.xml, build.gradle, *.csproj, *.sln, or *.slnx.
• Review error messages in the console output.

Cloud Coding Agent delegation problems:

• Make sure you have the right permissions to create GitHub Actions workflows.
• Check GitHub Actions permissions and quota limits for your organization.
• For .NET Framework apps, make sure Windows runner configuration is properly set.
• Check your MCP server configuration.

Next steps

After completing batch assessment, you can:

Continue the modernization workflow:

• Run batch upgrade across repositories - Apply consistent upgrades based on assessment findings.

Learn more:

• Create custom skills for organization-specific patterns.
• Learn about CLI commands.

Provide feedback

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