Edit

Quickstart: Install and use the GitHub Copilot modernization agent

This quickstart guides you through installing the GitHub Copilot modernization agent and using it to modernize a sample application.

Prerequisites

  • A GitHub Copilot subscription: Free, Pro, Pro+, Business, or Enterprise plan. See Copilot plans.
  • GitHub CLI: Install the GitHub CLI (gh) for authentication, version v2.45.0 or later. See Installing gh.

Platform requirements

  • Windows: x64 or ARM64.
  • Linux: x64 or ARM64 with glibc 2.27 or later (Ubuntu 18.04 or later, Debian 10 or later, Fedora 29 or later, Azure Linux 2.0 or later).
  • macOS: Apple Silicon or Intel.

Install the modernization agent

Use the following commands to install the modernization agent or update to the latest version.

Use one of the following options:

Option 1 - Winget (recommended):

winget install GitHub.Copilot.modernization.agent

For silent installation with no prompts:

winget install GitHub.Copilot.modernization.agent --silent

Option 2 - PowerShell one-liner:

iex (irm 'https://raw.githubusercontent.com/microsoft/modernize-cli/main/scripts/install.ps1')

Option 3 - MSI installer:

Download and run the latest MSI from the GitHub releases page.

Note

After installation, open a new terminal for the modernize command to be available on your PATH. These commands work for both initial installation and updating to the latest version. A dedicated version update command will be available in a future release.

Verify the installation:

modernize --version

Get a sample application

For this quickstart, use a sample application. Choose either Java or .NET:

git clone https://github.com/Azure-Samples/PhotoAlbum-Java.git
cd PhotoAlbum-Java
git checkout -b modernize

Use the interactive mode

The easiest way to get started is by using the interactive mode. First, authenticate by using the GitHub CLI:

gh auth login

Then, run the modernization agent:

modernize

The main menu appears:

○ How would you like to modernize your app?

  > Assess
    Analyze modernization readiness across one or multiple applications
    Plan
    Generate a structured plan to guide the agent
    Execute
    Run the tasks defined in the modernization plan

  Or select a quick-start scenario:

    Upgrade
    Upgrade runtimes and frameworks across one or multiple applications

Step 1: Assess the application

  1. Select Assess from the main menu.
  2. Choose how to specify your target repositories. You can select Current folder to use your current directory, Manual input to enter local paths or remote Git URLs, or From a config file to load repositories from a JSON config file. For this quickstart, select Current folder.
  3. Select assessment domains, such as Java upgrade and Cloud Readiness, and press Enter.
  4. Review the assessment configuration options, such as Analysis Coverage and Target Runtime. Press Enter on Continue to accept the recommended defaults, or adjust individual settings as needed.
  5. Choose the execution mode. Select Assess locally to run the assessment on your machine, or Delegate to Cloud Agents to let cloud agents run the assessment in parallel. For this quickstart, select Assess locally.
  6. Accept the default output path or enter a custom one, and then press Enter to start the assessment.
  7. Wait for the assessment to complete.

The assessment results are saved to .github\modernize\assessment\ in your project directory. The agent analyzes your code, dependencies, and configuration to identify:

  • Outdated framework versions
  • Deprecated APIs
  • Cloud compatibility issues
  • Migration opportunities

Step 2: Create a modernization plan

After the assessment finishes, the agent prompts you to create a modernization plan based on the identified problems:

○ How would you like to continue?

  > 1. Create modernization plan
       Generate a plan.md file according to the identified issues
    2. Return to main menu
  1. Select 1. Create modernization plan.
  2. Select 1. Keep the plan local to generate the plan on your machine, or choose 2. Submit to Cloud Agent to have a cloud agent generate it. Option 2 is experimental.
  3. The newly created assessment report is selected by default to generate the plan. Select 1. No report if you want to describe your specific requirements instead.
  4. Enter a plan name or press Enter to use the default name.
  5. Enter your modernization goal as a prompt. By default, the prompt is Based on the assessment report, upgrade the project and migrate to Azure to create a plan based on the assessment findings. You can replace it with any other migration request, for example:
    • migrate the database to Azure PostgreSQL
    • upgrade to Spring Boot 3
    • deploy to Azure Container Apps
  6. Press Enter to generate the plan.
  7. The agent analyzes your codebase and asks you to clarify the request. You can select a suggested answer or type your own.

The agent aggregates all the information and generates:

  • Plan file (.github/modernize/{plan-name}/plan.md): Detailed strategy and approach.

Tip

You can manually edit plan.md to add clarifications or adjust details.

Step 3: Execute the modernization plan

After you verify the plan, confirm that you want to execute the plan.

○ How would you like to continue?

  > 1. Execute modernization plan
       Run the tasks defined in the modernization plan
    2. Return to main menu
  1. Select 1. Execute modernization plan.
  2. Press Enter to execute the plan.
  3. Monitor progress as the agent applies changes.

The agent executes each task in order:

  • Makes code changes according to the plan.
  • Validates builds after each change.
  • Scans for and addresses CVEs.
  • Commits changes.

Step 4: Review the results

After execution finishes, you can review all changes that the agent made before merging them:

  1. Review changes: Check the modifications on the current branch.

    git status
git diff main

  2. Create a pull request: If you're satisfied with the changes, create a PR for team review.

    gh pr create \
    --title "Modernization: migrate the app to azure" \
    --body "Automated modernization by GitHub Copilot agent"

Next steps

Provide feedback

Your feedback helps improve the modernization agent. To send feedback from the Modernize TUI, press F.

GitHub Copilot modernization v1.0.0
GitHub Copilot modernization is AI-powered and may not always be accurate.

GitHub account: <username>
Copilot CLI version: 1.0.0
Model: Claude Sonnet 4.5 (1x) · M Select model · F Feedback

You can also create an issue in the github-copilot-appmod repository or use the GitHub Copilot modernization feedback form.

  • Last updated on